> ## Documentation Index > Fetch the complete documentation index at: https://developers.meshapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Error Reference > Every error code the API returns, which side of the call it belongs to, and what to do about it. Every failure returns the same envelope. `error.code` is stable and safe to branch on; `message` is for humans and may change. ```json theme={null} { "error": { "code": "context_window_exceeded", "message": "This model's maximum context length is 200000 tokens.", "provider_code": "context_window_exceeded" }, "request_id": "req_01JQ..." } ``` `code` is always present. `provider_code` appears when the failure came from a model provider and carries the more specific reason — branch on `code` first, then narrow on `provider_code` if you need to. Always log `request_id`. It is the only handle that ties your failure to our logs, and support cannot trace a report without it. ## Whose fault was it Errors fall into three classes. The class tells you whether to fix your request, fix your account, or retry. | Class | What it means | Typical status | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **Your request** | Something about the request itself was rejected. Retrying it unchanged will fail the same way. | `400`, `403`, `413`, `422` — whichever the model provider returned. | | **Your account** | The request was well-formed, but your account's own limits or balance stopped it. Nothing reached a model, and nothing was charged. | `401` unauthenticated, `402` out of credit or over a spend cap, `403` model not allowed, `429` rate limited. | | **Us or the model provider** | Nothing was wrong with your request or your account. Safe to retry with backoff — and often already retried for you before you saw this. | `429` upstream throttle, `500`/`502`/`503` unavailable, `504` timed out. | | **Depends on the individual results** | One code covering several attempts. Which side is at fault is in the per-attempt detail in the response body, not in the code itself. | Whatever the underlying attempts returned. | ## Your request Something about the request itself was rejected. Retrying it unchanged will fail the same way. | `error.code` | `provider_code` | What happened | What to do | | -------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `bad_request` | — | The request was rejected before reaching a provider — missing required fields or an invalid combination of options. | Check required parameters and their combinations against the API reference, then retry. | | `conflict` | — | The request was well-formed, but the resource is already in a state that refuses it — granting a role the user already holds, or revoking the last super\_admin. | Re-read the resource and retry against its actual state. This is not a payload problem: the same request may succeed later, or against a different resource. | | `content_policy_violation` | `content_policy_violation` | The provider refused the request because the prompt or generated content tripped its content filter. | Revise the prompt to comply with the provider's usage policy, or try a model with a different moderation policy. | | `context_window_exceeded` | `context_window_exceeded` | The request's input tokens (plus requested output) are larger than the model can accept. | Shorten the prompt, trim conversation history, or switch to a model with a larger context window. | | `invalid_api_version` | — | The X-Mesh-Version header named a version this API does not serve, was malformed, or was sent twice with different values. | Call GET /v1/api-versions for the supported labels and send exactly one of them, or omit the header to get the baseline version. | | `invalid_input` | `invalid_input` | An attached input (image, audio, file, or data URL) was corrupt, an unsupported format, or too large. | Verify the file is a supported format and within size limits, then re-encode or re-upload it. | | `invalid_request` | `invalid_request` | One or more request parameters were malformed, out of range, or unsupported by the model. | Check the request body against the API reference — verify parameter names, types, and value ranges. | | `invalid_request_error` | — | The request body was rejected before handling — a required field is missing, the wrong type, or malformed JSON. Returned by /v1/messages, which uses the Anthropic error envelope and answers schema problems with 400 rather than 422. | Read the message for the offending field path (for example 'max\_tokens: Field required'), correct the payload, and retry. | | `model_capability_not_supported` | — | The chosen model cannot serve the requested endpoint/capability (e.g. a chat-only model asked to embed or generate images). | Use an endpoint the model supports, or pick a model whose capabilities match the request. | | `model_not_found` | `model_not_found` | The requested model id is unknown to the gateway, disabled, or not permitted for this API key. | Call GET /v1/models for the exact enabled model ids, and confirm the key's allowed\_models includes it. | | `not_found` | — | The requested Mesh resource (key, template, batch, etc.) does not exist or is not visible to this key. | Verify the resource id and that it belongs to the same org/team as the key. | | `resource_not_found` | `resource_not_found` | A referenced resource (file id, batch id, previous response id, or fine-tune) does not exist or has expired. | Verify the id is correct and still valid; re-create the resource if it has expired. | | `unprocessable_entity` | — | The request was well-formed but semantically invalid — a generic user-input error with no more specific code. | Review the message detail and the request payload; correct the offending field and retry. | | `unsupported_operation` | `unsupported_operation` | The model or provider does not support the requested capability (e.g. tools, streaming, vision, this endpoint). | Remove the unsupported parameter/feature, or choose a model that supports it (see the model's capabilities). | | `validation_error` | — | FastAPI/Pydantic rejected the request body before handling — a field is missing, the wrong type, or malformed JSON. | Inspect the 'details' array in the response for the exact field paths, fix them, and retry. | ## Your account The request was well-formed, but your account's own limits or balance stopped it. Nothing reached a model, and nothing was charged. | `error.code` | `provider_code` | What happened | What to do | | ------------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | `concurrent_sessions_exceeded` | — | The account already has as many simultaneous realtime sessions as it is allowed. | Close an existing session before opening another, or request a higher concurrency limit. | | `feature_not_enabled` | — | The realtime API is not enabled for this deployment or account. | Contact support to have realtime enabled for your account. | | `forbidden` | — | The key is valid but not permitted to perform this action or reach this resource. | Use a key with the required permission, or request access from an org/team admin. | | `insufficient_credits` | `insufficient_credits` | For a bring-your-own-key request, the provider account has no remaining credit / a billing problem. | Top up credits or fix the billing method on the provider account tied to the BYOK key. | | `insufficient_quota` | — | The account behind this key has no remaining credit, so the realtime session was refused. | Add credits, then reconnect. | | `invalid_api_key` | — | The /v1/realtime socket was opened with a key that is missing, malformed, revoked or suspended. | Reconnect with an active rsk\_ key; create or rotate keys in the dashboard. | | `rate_limit_exceeded` | — | The API key exceeded its configured requests-per-minute or requests-per-day limit on the gateway. | Back off and retry after the Retry-After interval, or raise the key's RPM/RPD limit. | | `session_token_cap_exceeded` | — | This realtime session used the maximum tokens allowed for a single session. | Open a new session to continue; raise the per-session cap if you need longer conversations. | | `spend_limit_exceeded` | — | The API key hit its configured USD spend cap for the period. | Increase the key's spend limit or add credits to the account, then retry. | | `unauthorized` | — | The Mesh API key was missing, malformed, revoked, or does not exist. | Send a valid key as 'Authorization: Bearer rsk\_...'. Create or rotate keys in the dashboard. | | `upstream_auth_error` | `invalid_auth` | For a bring-your-own-key request, the provider rejected the supplied credential (401). | Verify the BYOK key is correct, active, and has access to the requested model; rotate it if compromised. | | `upstream_auth_error` | `permission_denied` | For a bring-your-own-key request, the credential is valid but not authorized for this model or action (403). | Grant the BYOK key access to the requested model/region in the provider's console, or use a key that has it. | | `upstream_rate_limit_error` | `monthly_quota_exceeded` | For a bring-your-own-key request, the credential has used up its allotted monthly quota. | Wait for the quota to reset or raise the quota/plan in the provider's console. | | `upstream_rate_limit_error` | `rate_limit_exceeded` | For a bring-your-own-key request, the provider throttled the credential (429). | Slow the request rate, add backoff, or request a higher rate limit from the provider. | ## Us or the model provider Nothing was wrong with your request or your account. Safe to retry with backoff — and often already retried for you before you saw this. | `error.code` | `provider_code` | What happened | What to do | | ------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ | | `api_version_migration_failed` | — | Your request is pinned to an older API version and the gateway failed while converting the response back to that version's shape. Nothing wrong with your request. | Retry; if it persists, contact support with the request\_id. Pinning to a newer version avoids the conversion entirely. | | `connection_timeout` | — | The gateway stopped receiving heartbeats on the socket and closed it, usually a network interruption. | Reconnect; if it recurs, check for a proxy or network path that drops idle WebSockets. | | `gateway_timeout` | `provider_timeout` | The upstream provider did not return a response within the gateway's timeout. | Retry the request; for long generations reduce max\_tokens or enable streaming. If it persists, the provider is slow. | | `idle_timeout` | — | The realtime socket was idle for longer than the allowed window and was closed. Expected behaviour, not a failure. | Reconnect when you next need the session; send periodic activity to keep one open. | | `internal_error` | — | An unhandled exception occurred inside the gateway — not attributable to your request. | Retry once; if it persists, contact support with the request\_id so we can trace the failure. | | `provider_error` | — | The upstream realtime provider returned an error mid-session. Not caused by your request. | Reconnect; if it repeats, report it with the request\_id. | | `provider_not_available` | — | The model's provider is configured but its adapter is not registered (missing platform credentials) or a circuit breaker is open. | This is a server-side configuration/health issue, not your request. Retry later or use another model; escalate if it persists. | | `provider_resource_not_found` | — | The video provider no longer recognises this task id — typically because it expired on their side before it was collected. | Submit the generation again; poll and download results promptly. | | `service_draining` | — | The instance serving your socket is being drained for a deploy, so the session was closed cleanly. | Reconnect — a new instance will accept the session immediately. | | `session_duration_exceeded` | — | The realtime socket hit the maximum lifetime for a single session and was closed. | Reconnect to continue; sessions are bounded by design. | | `upstream_error` | `bad_response` | The provider returned HTTP 200 but a body the gateway could not parse (truncated or malformed). | Retry the request. If it reproduces on a specific model, report it with the request\_id so we can inspect the raw body. | | `upstream_error` | `connection_error` | A network, DNS, or TLS failure prevented the gateway from connecting to the upstream provider. | Retry shortly. If it persists across models, it is a provider or network incident — check the incident channel. | | `upstream_error` | `internal_provider_error` | The upstream provider returned a server-side error, or a platform credential/billing/quota issue is being kept opaque. Not caused by your request. | Retry with backoff. If it persists across models, check the provider's status page and our incident channel. | | `upstream_error` | `provider_overloaded` | The upstream provider reported it is overloaded / at capacity (e.g. Anthropic 529, provider 503). | Retry with exponential backoff, or route to an alternate model/provider for this request. | | `upstream_error` | `unknown` | The provider failed with an error the gateway could not map to a specific category. | Retry with backoff and report the request\_id — an unclassified error usually needs a new classifier entry. | | `upstream_overload` | — | The upstream provider refused the session because it is overloaded. | Retry with backoff, or try a different realtime model. | ## Depends on the individual results One code covering several attempts. Which side is at fault is in the per-attempt detail in the response body, not in the code itself. | `error.code` | `provider_code` | What happened | What to do | | ------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `all_models_failed` | — | POST /v1/compare fans out to several models and none returned a response, so there is nothing to compare or synthesise. This code says only that every attempt failed — WHY is in the per-model errors. | Read the per-model errors in the response body. If they name something in your request, fix that and retry; if they all report the provider unavailable, retry with backoff or narrow the model list. | ## Where it failed Failed requests in the dashboard logs carry a `failure_stage` — how far the request got before it stopped. Successful requests have none. | Stage | Meaning | | -------------------- | --------------------------------------------------- | | `auth` | Authenticating the API key. | | `guard_rate_limit` | Checking your requests-per-minute / per-day limits. | | `guard_spend_cap` | Checking your USD spend caps. | | `guard_model_access` | Checking the key is allowed to call this model. | | `template` | Resolving and rendering a prompt template. | | `balance` | Checking the account's credit balance. | | `credentials` | Resolving the upstream credential for the model. | | `upstream_submit` | Sending the request to the model provider. | | `upstream_stream` | Reading the streamed response back. | | `settlement` | Recording usage and settling the charge. | ## What errors never contain Messages are stripped of upstream internals before they reach you — SDK call frames, cloud resource identifiers and anything credential-shaped. Two consequences worth knowing: * **Which provider served a request is not disclosed.** A model is reachable through more than one upstream and we may fail over between them, so the provider is not part of the contract. `X-Mesh-Routing-*` response headers tell you *that* a fallback happened, not to where. * **A problem with our own upstream account reads as a provider outage.** If one of our provider credentials is rejected or throttled, you get `upstream_error` with a generic message rather than the specific cause. When you use your own provider key (BYOK) the real error is forwarded to you, because the account is yours to fix.