Errors and retries
Classify failures correctly and retry only when another attempt can help.
Do not retry every non-success response. Blind retries increase cost, duplicate work, and can turn a small outage into a larger one.
Response classes
| Status | Meaning | Typical action |
|---|---|---|
400 | Request rejected by endpoint logic | Fix the request; do not retry unchanged. |
401 | Missing, invalid, or revoked credential | Refresh or replace the credential. |
403 | Authenticated but not authorized | Fix scopes, role, visibility, or allowlist. |
404 | Resource absent or intentionally hidden across an org boundary | Verify the identifier and organization context. |
409 | State or idempotency conflict | Read the detail and reconcile state. |
422 | Request body or parameters failed schema validation | Fix the payload; do not retry unchanged. |
429 | Rate or capacity limit | Back off and respect retry guidance. |
5xx | Server or dependency failure | Retry with bounded exponential backoff. |
Malformed API payloads answer 422, not 400 — request validation runs before
endpoint logic, so a missing field, a wrong type, or an out-of-range value is a
422. Treat 400 and 422 the same way when retrying: both mean the request
itself is wrong.
Do not confuse that synchronous response with output-schema verification. An
agent run is admitted before its output exists. If an otherwise successful
response later fails the agent's Draft 2020-12 output contract, the start request
does not retroactively become a 422; the run ends with status=failed,
verification_status=verification_failed, and a schema-validation error. Fix
the agent output or its configured contract before retrying.
A 429 carries Retry-After when the limit has a known window; concurrency
limits always set it, while daily caps and budget stops usually do not, because
they clear at midnight UTC or need an operator to act.
Retry policy
Use exponential backoff with jitter, a maximum attempt count, and an overall deadline. Preserve the same idempotency key when retrying the same execution start.
Retry 5xx, and 429 after the indicated delay. Do not retry validation, permission, or visibility failures until something material changes. Default any status you do not recognize to non-retryable rather than retryable.
Diagnostics
Record the HTTP status, request or correlation identifier, endpoint, attempt number, and safe error detail. Redact Bearer tokens, trigger tokens, secrets, and sensitive payloads.