Errors
OpenAI and Anthropic error envelopes, the codes, what to do about them and which requests to retry.
An error comes in the envelope of the format you sent the request in — the way
your SDK understands it. Include request_id when contacting support; it also
comes in the x-request-id header of every response.
Every endpoint except /v1/messages uses the OpenAI envelope:
{"error": {"message": "...", "type": "...", "code": "...", "param": "...", "request_id": "req_..."}}
/v1/messages uses the Anthropic envelope; our code and param are extra
fields inside error, and request_id is at the top level:
{"type": "error", "error": {"type": "not_found_error", "message": "...", "code": "model_not_found"}, "request_id": "req_..."}
The param field is present only when the error concerns a specific parameter.
error.type in the Anthropic envelope depends only on the HTTP status:
400 — invalid_request_error, 401 — authentication_error,
402 — billing_error, 403 — permission_error, 404 — not_found_error,
413 — request_too_large, 429 — rate_limit_error, 500 and 502 — api_error,
503 — overloaded_error.
Error codes
| HTTP | code | What it means |
|---|---|---|
| 400 | invalid_request | Malformed request body (no model, broken JSON) — check the parameters. A provider rejection the gateway could not classify uses the same code; the HTTP status is then the provider's (4xx). |
| 400 | unsupported_parameter | A request parameter is not supported — its name is in the param field. Remove it and retry. See Request parameters. |
| 400 | unsupported_value, invalid_value | The model's provider rejected a parameter value; the parameter name is in the param field when it could be determined. |
| 400 | context_length_exceeded | The request does not fit the model's context window. The message starts with “Prompt is too long:” — Claude Code uses it to trigger context compaction. |
| 400 | content_policy_violation | The model's content policy rejected the request — change the prompt. |
| 400 | invalid_image | The model rejected the reference image — try a different one. |
| 401 | invalid_api_key | Key missing, not found or revoked — check the Authorization header. |
| 402 | insufficient_quota | Balance exhausted — top up your account. If the remainder is held by requests in progress, retry once they finish. |
| 403 | spend_limit_exceeded | This key hit its spend limit — raise the limit or create a new key. |
| 404 | model_not_found | The model does not exist, is disabled, is not available to your account or does not fit the endpoint (an image model on chat) — check GET /v1/models with your key. |
| 404 | not_found | Unknown endpoint, video job not found or the video is not ready yet. |
| 413 | invalid_request | The request body exceeds the limit — see Limits. |
| 422 | generation_failed | The model returned no image. Retry the request or rephrase the prompt. |
| 429 | rate_limit_exceeded | Too many concurrent requests on your account, or the model is overloaded at the provider. Retry after the pause in the Retry-After header. |
| 500 | — | Internal gateway error (type: server_error, no code). Retry; if it persists, contact support with the request_id. |
| 502 | upstream_unavailable | The model's providers are temporarily unavailable — retry later. |
| 503 | service_unavailable | Service under maintenance or temporarily unavailable — retry later. |
| 503 | — | The model has no available routes right now (type: server_error, no code) — retry later or pick another model. |
Retries
Retrying makes sense for 429, 500, 502, 503 and 422. Other errors will not go away on retry — fix the request, key or balance first.
- On
429wait for the pause in theRetry-Afterheader; without it, use exponential backoff (1, 2, 4… seconds). The OpenAI and Anthropic SDKs do this themselves. - An error that arrives as an event mid-stream is also a reason to retry the whole request (see Streaming).
Stuck? Email us at support@example.com with the request_id from the response.
Updated September 29, 2026