Skip to content

Errors, timeouts and failover

OpenAI-style endpoints (/v1/* except Anthropic Messages and Gemini, and /prism/*) return:

{"error": {"type": "invalid_request_error", "code": "invalid_request", "message": "...", "param": null}}

The X-Prism-Error-Class header repeats code, so a client can branch on it without parsing the message. X-Request-Id identifies the request.

/v1/messages uses the Anthropic shape, /v1beta/... the Google shape and /api/* the Ollama shape; see Ingress dialects. The codes below are the same; only the envelope differs.

Code HTTP Meaning
invalid_request 400 Malformed JSON, invalid field, unknown model, invalid prism intent
invalid_request_size 400 Body over [server] max_request_body_bytes (default 4 MiB), or top_n above 128 on rerank. Prism answers 400, not 413
session_identity_conflict 400 X-Prism-Session and body session_id differ
unauthorized 401 Managed address: no valid key. A request with a Prism key on either address: the key is revoked, expired or unknown, or the request carries a query parameter that is not accepted with a key. For one key that is revoked, expired or unknown (an app that was disconnected included), the message is “This Prism key is not valid: it was revoked or expired, or the app was disconnected. Sign in again from the app, or use a current key.”; every other case has the message unauthorized. Control and status endpoints: no valid token
billing_required 402 Every provider tried asks for payment or a top-up
forbidden 403 Managed address: the key’s policy does not allow the request, or the request carries a header the managed address refuses
corporate_unavailable 403 A paid feature without an active subscription whose edition includes it; the body adds unavailable{capability, reason, message, requires}, where requires is the lowest edition that opens it (pro, teams or enterprise). When the edition does not include the feature (reason: edition_required) or no subscription is bound, the message is “This feature needs Prism . Please upgrade your plan.”
batch_spend_unverifiable 403 Batch creation on the managed address
openai_access_suspended 403 Teams and Enterprise: the organization suspended your requests to OpenAI models and no other company’s model can serve this request
route_not_found 404 No endpoint at that method and path
channel_gone 410 Every provider tried reports the model as permanently gone
budget_exceeded 429 A [[budget.limits]] threshold with action = "reject" was reached, or every route of the request is closed by a spent [[budget.account_limits]] or [[budget.model_limits]] entry; Retry-After says when the earliest window resets
server_error 500 Configuration or internal error
endpoint_not_supported 501 File, image, audio or batch endpoint with no OpenAI-compatible provider
upstream_error 502, or the provider’s status The provider failed. A provider’s own JSON error body is passed on with its status, and X-Prism-Upstream-Status names that status
all_attempts_failed provider’s status Every attempt of a routed request failed; see below
overload 503, Retry-After: 5 Prism’s request queue is full
providers_unavailable 503 No provider can serve the request now (none connected, all unhealthy, or none offers the API). May carry prism_switch_offer
providers_rate_limited 503, provider’s Retry-After Every provider tried is rate limited
no_eligible_executor 503 The request’s requirements (local-only, capabilities, quality, effort) leave no model; error.prism lists the exclusions
privacy_route_unavailable 503 A local-only request and no local model that can serve now; error.prism.exclusions names each local route that is out, its health state and the class behind it
timeout 504 A provider or the queue did not answer in time

Retry overload and timeout with a delay, not at once.

Console and administration endpoints add codes of their own. Two of them concern editions: 409 seat_limit (“every paid seat is taken; add seats to the subscription first”) when an invitation would bring in a person beyond the installation’s seat limit (Free 3; Pro and Teams their paid seats, at most 5 and 10; Enterprise its paid seats), and 409 edition_limit (“several teams need Prism Enterprise”) for a second team below Enterprise.

A provider::model pin to an OAuth account awaiting reauthentication returns 503 providers_unavailable, not an unknown-model 400. Its message directs the connection owner to Connections in the Prism console to sign in again. This applies to Chat, Messages and Responses and does not switch to a sibling account. There is no Retry-After: retrying alone cannot repair the login. Unknown connection names still return 400 invalid_request.

When Prism tried several models and all failed, it returns:

{"error": {"type": "upstream_error", "code": "all_attempts_failed",
"message": "auto route failed on all attempted providers: claude-oauth/claude-opus-5-5 content_filter, openrouter/z-ai/glm-5.3-flash unavailable",
"attempts": [{"provider": "...", "model": "...", "status": 503, "reason": "...", "latency_ms": 812}]}}

The message names each provider and model tried with its reason, for clients that show only the message. X-Prism-Attempts, X-Prism-Attempt-Providers and X-Prism-Attempt-Reasons summarise the same list. content_filter means the provider withheld the answer (finish_reason: content_filter, Anthropic stop_reason: refusal). The body holds no request content, provider response or credential.

For a request Prism routes itself (auto, a strategy, a role, a bare model id), an attempt that fails with a retryable error (timeout, 5xx, rate limit, unavailable model, a model refusing the request with 403) moves to the next candidate in the order. A model that refused a client this way is skipped for that client, recognised by its User-Agent, for the next six hours; other clients still reach it. The tool results of a tool loop go to the model that asked for the tools; only when that model withholds its answer (content_filter) does the turn move to the next model. Prism never retries after the first byte of a streamed answer has reached the client.

When an OpenAI model refuses a request (content_filter, or an OpenAI invalid_prompt usage-policy rejection), Prism does not send it to any other route to an OpenAI model: not another subscription account, not the OpenAI API, not OpenRouter openai/* or another reseller. OpenAI’s Usage Policies forbid working around its safeguards. Models of other creators are still tried; gpt-oss served by another company counts as that company’s model. The routing record carries openai_refusal_held: true.

An Anthropic model’s refusal is held the same way (content_filter: Anthropic stop_reason: refusal, or a usage-policy rejection): Prism does not send the request to another route to an Anthropic model, whether another Claude subscription account, the Anthropic API or OpenRouter anthropic/*. Anthropic’s Usage Policy from 2026-11-12 forbids coordinating across accounts to circumvent its guardrails. Other creators’ models are still tried, and a rate limit or server error of a Claude route is not a refusal. The routing record carries anthropic_refusal_held: true.

A provider::model request stays on that provider unless failover to other providers is allowed; see Choosing a model.

A 429 marks only that model as cooling down, not the whole provider. A provider is marked unhealthy when two of its models fail within about a minute, or on authentication, transport or gateway errors. An unhealthy provider returns to routing after its probes succeed again.

An answer that names a capability the model does not have, or that blames the request itself, is never counted against the model or the provider, whatever HTTP status the provider chose. A text-only model answering an image request (image input is not supported, Multimodal projector is not loaded, At most 0 image(s), or OpenRouter’s No endpoints found that support image input) records vision=false for that route and stays in routing; so does a request the server could not read (Failed to load image, Unable to process input image, Invalid content type) and an ordinary bad parameter. Credential and funding refusals still take the account out, a model the account may not use stays refused, and a model the provider no longer lists still leaves routing.

Phase Remote provider Self-hosted / local provider
Stream opening (until the provider answers with HTTP 200) 8 s; 60 s for models that reason before answering 90 s
Whole non-streaming attempt 120 s; 600 s for models that reason before answering 600 s
Silence inside a running stream 120 s 600 s

A model counts as reasoning when its provider’s model list says so, when another provider that sells the same model says so (a vendor’s own list often does not), or when one of its answers through this Prism carried reasoning text or reasoning tokens. Only a list that says the model does not reason, with no such answer seen, keeps it at the shorter wait.

A provider counts as self-hosted when its address is loopback, a private network, 100.64.0.0/10 or .local, or when self_hosted = true is set. Change the values in [runtime_policy]:

[runtime_policy]
stream_open_timeout_remote_ms = 8000
stream_open_timeout_remote_reasoning_ms = 60000
stream_open_timeout_ms = 90000 # self-hosted/local providers
upstream_request_timeout_remote_ms = 120000
upstream_request_timeout_remote_reasoning_ms = 600000
upstream_request_timeout_local_ms = 600000
stream_idle_timeout_remote_ms = 120000 # 0 disables
stream_idle_timeout_local_ms = 600000 # 0 disables

Models that think for a long time before the first token can trip a client’s own stream timeout. /v1/models gives each chat model a prism.ttfb entry: class: "thinking" means its 90th-percentile time to first byte through this Prism is 8 seconds or more. To keep a client connection alive during that silence on a Chat Completions stream sent straight to one model, set [server] stream_open_keepalive_ms (for example 5000): after the provider answers HTTP 200, Prism sends SSE comment lines until the first byte arrives. Off by default. It does not apply to Responses streams or to streams Prism buffers to check the answer before passing it on (default routing of auto streams).