Gateway error codes
Every error code the Gateway's /v1 endpoints return, with its HTTP status, whether retrying can help, and what fixes it.
Where the code is#
Each endpoint answers in its own protocol's error shape, so the official SDKs read it:
/v1/chat/completionsand/v1/responses:{"error": {"message", "type", "param", "code"}}. The code is inerror.code./v1/messagesand/v1/messages/count_tokens:{"type": "error", "error": {"type", "message"}}. The code is the message, except on a 429, which carries a readable message and the code inerror.code./v1/modelsanswers in the shape of the client that asked: the Anthropic shape when the request sendsanthropic-versionorx-api-key, otherwise the OpenAI shape.
A refusal the provider itself wrote (a 400, 413 or 422 about your request's content) is passed on in the provider's own words and has no Gateway code.
Retry headers: Retry-After says how many seconds to wait. X-Should-Retry: false tells the OpenAI and Anthropic SDKs not to retry at all.
Is it the Gateway?#
Getting 5xx errors, or no answer at all? The Gateway status page checks from your browser, with no sign-in, whether our hosted Gateway is ready, and says what to do for each answer.
Catalog#
| Code | Status | Retry | What to do |
|---|---|---|---|
application_key_required | 401 | No | Send the key as Authorization: Bearer <key> (or x-api-key, except on /v1/chat/completions). |
application_key_not_accepted | 401 | No | The key is revoked, expired, mistyped or used from an address outside its allowlist. Check it on the keys list, or create a new one. |
gateway_key_attempts_exceeded | 429 | After Retry-After | Too many keys that are not accepted came from your address. Fix the key your tool sends, then wait. |
gateway_key_model_not_allowed | 403 | No | The key's model allowlist does not include this model. Use a listed model or auto, or change the key's allowlist. |
server_application_required | 403 | No | The request came from a browser (Origin header) or had an unexpected query string. Call the Gateway from a server, CLI or script. |
inference_not_admitted | 403 | No | This workspace cannot use the Gateway right now, or the chosen model cannot be used. Request access on the AI Gateway page. |
model_not_enabled | 403 | No | The workspace's model settings exclude this model. Use another model or auto, or ask an owner or admin to allow it. |
model_not_found | 404, 400 | No | The model is unknown, or no allowed model can serve the request on this endpoint. Use a name from GET /v1/models or auto. |
video_not_found | 404 | No | No video with this id was created with this API key. A video is read only with the key that created it. |
invalid_model | 400 | No | agentlab/… names are not models. Use auto or a name from GET /v1/models. |
invalid_provider | 400 | No | provider.only names something that is not a provider, leaves out the model you named, or lists providers with no model that can serve the request (error.param is provider.only). Fix the list; the message names the valid providers. |
unsupported_parameter | 400 | No | The request names an OpenAI field the Gateway does not accept (error.param names it). Remove that field. |
prompt_reference_invalid | 400 | No | Name the prompt by its id or slug in /v1/prompts/{prompt}/completions, optionally followed by @<version>. |
prompt_not_found | 404 | No | The key's workspace has no prompt, or no such version, by that name. Check the Prompts tab of the workspace the key belongs to. |
prompt_variables_mismatch | 400 | No | variables must name exactly the prompt's variables. The message lists the missing ones and the ones the prompt does not use. |
prompt_variables_invalid | 400 | No | variables must be an object whose values are strings. |
prompt_messages_not_accepted | 400 | No | A prompt call sends variables, not messages: the prompt holds the messages. |
prompt_too_large | 400 | No | The prompt filled with these variables is larger than a request may be. Send shorter values. |
invalid_inference_request | 400 | No | The Chat Completions body uses a field or value the Gateway does not accept. See the API reference. |
invalid_request | 400 | No | The Responses body asks for stored state (previous_response_id, conversation, prompt) or a refused tool. param names the field. |
request_key_invalid | 400 | No | Idempotency-Key must be sent at most once and be 8 to 128 characters. |
request_key_already_used | 409 | No | This Idempotency-Key was already used. Send a new key with a new request. |
routing_header_invalid | 400 | No | X-AgentLab-Routing must be exactly auto, sent once. |
invalid_metadata | 400 | No | The tags in X-AgentLab-Metadata or the body's metadata cannot be recorded; the message says which rule they broke. Send one JSON object of at most 16 string values, keys of 1 to 64 letters, digits, _, . or -, values of 1 to 512 characters. See tags. |
json_required | 415 | No | Send Content-Type: application/json. |
request_too_large | 413 | No | The body is larger than the endpoint accepts: 1 MiB for Chat Completions, speech and image generation, 32 MiB for Messages and Responses, 26 MiB for transcriptions (an audio file of at most 25 MiB), 64 MiB for image edits and videos. |
request_body_unreadable | 400 | Yes | The request body ended before the length it declared, or did not arrive in time. Send the request again. |
gateway_guardrail_blocked | 400 | No | A workspace guardrail found something it blocks (a card number, an API key, a listed word, …); the message names the check. Remove that content, or ask a workspace admin to change the guardrail in AI Gateway › Get started. |
inference_allowance_exceeded | 429 | No | A monthly limit, department ceiling or rolling window has no room. The message names it. Raise it, or wait for the reset. On Free it can be the plan's included requests or model spend (gateway_plan_requests, gateway_plan_spend); on Pay as you go, the credit balance (gateway_balance). Add credits under AI Gateway › Plan; the same key works right after. |
gateway_rate_limited | 429 | After Retry-After | This key or workspace sent more requests or tokens per minute than its rate limit, or has as many audio, image and video requests in progress as the Gateway serves at once. Wait, or raise the limit. |
provider_rate_limited | 429 | After Retry-After | The model provider is busy. The SDKs wait and retry on their own. |
count_tokens_concurrency_exceeded | 429 | After Retry-After | Too many token-count requests at once. Retry after a second. |
provider_overloaded | 529 | Yes | The model provider is overloaded. Retry shortly, or use auto or another model. |
inference_failed | 502 | Yes, once | The provider failed to answer. If it keeps failing, open the request under AI Gateway › Usage. |
settlement_pending | 503 | No | The model answered but its usage could not be recorded yet, so the answer was withheld. Don't resend: it settles on its own. |
inference_unavailable | 503 | Yes | The Gateway could not reach what it needed to decide. Retry shortly. |
gateway_unavailable | 503 | Yes | The Gateway server is starting or reloading its configuration. Retry shortly. |
gateway_not_configured | 503 | No | This server has no Gateway configured. On a self-hosted Gateway, check its deployment configuration. |
transport_deadline_unavailable | 503 | Yes | The server could not set up the connection's time limits. Retry. |
This table is checked against the Gateway's code on every build: a code the Gateway can send without a row here fails the build.