--- title: Gateway error codes description: Every error code the Gateway's /v1 endpoints return, with its HTTP status, whether retrying can help, and what fixes it. url: https://agentlab.cresclab.com/docs/en/gateway/errors language: en updated: 2026-10-28 --- # 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/completions` and `/v1/responses`: `{"error": {"message", "type", "param", "code"}}`. The code is in `error.code`. - `/v1/messages` and `/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 in `error.code`. - `/v1/models` answers in the shape of the client that asked: the Anthropic shape when the request sends `anthropic-version` or `x-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](https://agentlab.cresclab.com/en/status) 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 ` (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](https://agentlab.cresclab.com/en/gateway#demo). | | `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 `@`. | | `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](https://agentlab.cresclab.com/docs/en/gateway/api.md#chat-completions). | | `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](https://agentlab.cresclab.com/docs/en/gateway/usage.md#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.