Error Reference

Every failure returns the same envelope. error.code is stable and safe to branch on; message is for humans and may change.

{
  "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.

Introduction

Accounts & Access

Core Inference

Retrieval & Search

Multimodal

Operations

Mesh CLI

Platform

Reference

Whose fault was it

Your request

Your account

Us or the model provider

Depends on the individual results

Where it failed

What errors never contain

​Whose fault was it

​Your request

​Your account

​Us or the model provider

​Depends on the individual results

​Where it failed

​What errors never contain

Whose fault was it

Your request

Your account

Us or the model provider

Depends on the individual results

Where it failed

What errors never contain