Errors, timeouts and failover
Error shape
Section titled “Error shape”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 |
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.
All attempts failed
Section titled “All attempts failed”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.
Failover
Section titled “Failover”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.
Timeouts
Section titled “Timeouts”| 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 = 8000stream_open_timeout_remote_reasoning_ms = 60000stream_open_timeout_ms = 90000 # self-hosted/local providersupstream_request_timeout_remote_ms = 120000upstream_request_timeout_remote_reasoning_ms = 600000upstream_request_timeout_local_ms = 600000stream_idle_timeout_remote_ms = 120000 # 0 disablesstream_idle_timeout_local_ms = 600000 # 0 disablesModels 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).