Developers / fail closed

Errors & retries

An error is a state to handle, not a reason to send the same action again. Keep the status, stable code, request ID, and recovery metadata together.

One rule for mutations

When a mutation times out, fetch its operation or receipt before trying again. If you retry, reuse the same Idempotency-Key and X-Agent-Run-Id.

Open operations guide

Choose the safe next step

Status	What it means	Do this next
`400`	Malformed request or invalid state.	Fix the payload; do not retry unchanged.
`401`	Session or Agent API key is missing, expired, or invalid.	Re-authenticate or ask the owner for a current key.
`403`	The key lacks the required scope or role.	Read the manifest and request the smallest missing scope.
`409`	Idempotency or lifecycle conflict.	Fetch the operation or receipt before deciding.
`422`	Validation, suppression, or readiness boundary.	Resolve the named field or boundary; never force it through.
`429`	Rate or plan limit.	Honor `Retry-After` or reset time, then retry only if safe.
`502–504`	Transient service or provider failure.	Retry bounded, idempotent reads; inspect mutation state first.

Read the error shape

Prefer the stable code over matching message text. Preserve request_id when returned.

{
  "detail": {
    "code": "SCOPE_MISSING",
    "message": "The key does not grant leads:read.",
    "request_id": "req_…",
    "next_action": "Use a key with the required scope."
  }
}

Retry checklist

Keep the same run ID.It ties related requests to one investigation.
Reuse the same idempotency key.A new key can create a duplicate action.
Read the receipt.A provider timeout is not proof that nothing happened.
Record the disposition.Keep the final status and next owner visible.