Errors

Every failure carries one canonical error class — a short stable string like rate_limit or insufficient_quota — in a fixed spot in the body and in the x-tm-error-code response header. The body's native shape follows the surface you called (OpenAI-compatible or Anthropic-compatible), so your SDK's built-in error handling keeps working; the canonical class is there so your code never has to parse prose.

A failure that happened after your request was accepted — at a limit, at a provider, or in our infrastructure — also says where it came from. The x-tm-error-origin header (and origin in the body's metadata) is one of gateway_admission (a limit or balance of yours), upstream_quota (a provider's declared capacity), upstream (the provider answered), gateway_infrastructure (our side) or authorization (your key or connection). When a limit refused the request, x-tm-limit-scope, x-tm-limit-kind and, where known, x-tm-limit-id name it. See Limits and capacity.

Where the class lives

OpenAI surface (POST /v1/chat/completions):

{
  "error": {
    "code": "model_unavailable",
    "message": "model \"gpt-5-nano\" is not in the catalog; GET /v1/models lists what this key can serve",
    "type": "invalid_request_error",
    "metadata": { "error_type": "model_unavailable" }
  },
  "request_id": "6f8f57b2-..."
}

Anthropic surface (POST /v1/messages):

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model \"gpt-5-nano\" is not in the catalog; GET /v1/models lists what this key can serve",
    "error_type": "model_unavailable"
  },
  "request_id": "6f8f57b2-..."
}

Six rules govern these bodies:

• error.metadata.error_type (OpenAI surface) or error.error_type (Anthropic surface) is always the canonical class. Every error body is generated by the gateway; a provider's raw error body is never relayed. The provider's HTTP status is in x-tm-upstream-status when it answered.
• When a provider refused the request, the message carries the provider's own words: upstream <route> returned <status>: <words>, for example upstream anthropic returned 400: messages.1.output_config: Extra inputs are not permitted. The words are the message of the provider's JSON error, on one line and at most 1,000 characters, with links, host names, keys and account, organization and project ids replaced by a marker. Coding agents read these words to drop a feature the provider refused and retry. No words are shown when the provider's error is not JSON, when it would repeat our key, or, on a marketplace route, when it is about our provider account (a 401, 402, 403 or 429, credit, billing or quota): then the message is upstream <route> returned <status>. On your own connection (BYOK) you get the words about your account too. A closed dedicated endpoint never shows a provider's words, and dedicated capacity is named routerplus.
• On the Anthropic surface, error.type additionally maps to the native Anthropic type string (rate_limit_error, billing_error, ...) so the Anthropic SDK's own error classification and retry behavior work unmodified.
• On the OpenAI surface, error.code carries the canonical class. Switch on metadata.error_type, error.code, or the HTTP status — not on error.type, which is a generic string. There are three exceptions, all byte-matching OpenAI's own wire so OpenAI SDKs and coding agents recognize them natively: out-of-credits, where both code and type are insufficient_quota; a prompt too long for the model, where code is context_length_exceeded (see Context overflow); and a rate limit on /v1/chat/completions and /v1/responses, where code is rate_limit_exceeded and type is requests, or tokens for a token limit.
• Errors raised before routing (bad key, unknown route, a crash in our handler) pick the shape from the path: requests to /v1/messages get Anthropic-shaped bodies, everything else OpenAI-shaped.
• On POST /v1/responses, a model served through the chat translation (Claude and the other models that OpenAI does not serve) gets OpenAI's own codes where clients act on them: rate_limit_exceeded, context_length_exceeded, model_not_found and invalid_prompt in error.code, with the canonical class still in error.metadata.error_type. See POST /v1/responses.

The metadata carries a few more fields after a limit or a balance refused the request: origin, limit_scope, limit_kind, limit_id, retryable, and retry_at or reset_at when one is known. On the OpenAI surface they sit beside error_type in error.metadata; on the Anthropic surface in error.metadata.

The canonical classes

When the status comes from a provider, the provider's own HTTP status is also exposed in the x-tm-upstream-status header.

On POST /v1/decisions, GPT-6 Luna Decisions can decline one question and answer the rest. That is not an error: the response is a 200, the declined question's answer is {"type": "refusal"}, and the call is billed. Check each answer's type.

Context overflow

A prompt longer than the model's context window is a 400 in the standard shape of the surface you called, because coding agents (Claude Code, Codex, Cursor, Cline and others) look for these exact words before they compact the conversation and retry. M is the model's context window in tokens, and N is the size of your prompt. The status is 400 whatever the provider sent; x-tm-upstream-status keeps the provider's.

OpenAI surface (POST /v1/chat/completions):

{
  "error": {
    "code": "context_length_exceeded",
    "param": "messages",
    "message": "This model's maximum context length is M tokens. However, your messages resulted in N tokens. Please reduce the length of the messages.",
    "type": "invalid_request_error",
    "metadata": { "error_type": "context_overflow" }
  },
  "request_id": "..."
}

Anthropic surface (POST /v1/messages):

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "prompt is too long: N tokens > M maximum",
    "error_type": "context_overflow"
  },
  "request_id": "..."
}

When the input fits but the input and the output limit together do not, the words say so: … However, you requested T tokens (N in the messages, K in the completion). Please reduce the length of the messages or completion. on the OpenAI surface, and input length and `max_tokens` exceed context limit: N + K > M, decrease input length or `max_tokens` and try again on the Anthropic surface. The numbers come only from the provider's own words; when it gave none, the message is This model's maximum context length was exceeded. Please reduce the length of the messages. or prompt is too long for the model's context window. POST /v1/responses uses the same code, context_length_exceeded.

The canonical class stays context_overflow in error_type and in the x-tm-error-code header. The request is not sent to another provider, and nothing is billed for it. context_length in /api/models.json gives each model's window.

What to do, per class

Failure headers

x-tm-error-code is not CORS-exposed; browser code reads the class from the body.

Strict by design

Five refusals people trip on are deliberate — the alternative in each case is billing you for something wrong.

n>1 is a typed 400, not a degraded answer. The normalizer emits exactly one choice; accepting n: 4 and silently billing a garbled single-choice response would be dishonest.

curl -s https://api.routerplus.com/v1/chat/completions \
  -H "Authorization: Bearer $TM_API_KEY" -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","n":4,"messages":[{"role":"user","content":"hi"}]}'

{
  "error": {
    "code": "invalid_request",
    "message": "n>1 is not supported in v1; request a single choice",
    "type": "invalid_request_error",
    "metadata": { "error_type": "invalid_request" }
  },
  "request_id": "..."
}

Content a model does not take is a typed 400, not an answer that ignored it. A provider that does not read images can drop the image, answer the rest, and still bill the request. So an image, file, audio or video part goes only to a route whose listing takes that kind, and a part that no route of the model takes is refused before anything is reserved or sent. GET /v1/models lists what each model takes in architecture.input_modalities.

curl -s https://api.routerplus.com/v1/chat/completions \
  -H "Authorization: Bearer $TM_API_KEY" -H "content-type: application/json" \
  -d '{"model":"gpt-4.1-mini","messages":[{"role":"user","content":[{"type":"text","text":"What is said in this recording?"},{"type":"input_audio","input_audio":{"data":"UklGRiQAAABXQVZF","format":"wav"}}]}]}'

{
  "error": {
    "code": "invalid_request",
    "message": "messages[0].content[1]: model \"gpt-4.1-mini\" does not take audio input; it takes text, image and file",
    "type": "invalid_request_error",
    "metadata": { "error_type": "invalid_request" }
  },
  "request_id": "..."
}

No silent model substitution. An unknown model id is a 404 whose message echoes exactly the string you sent — we never quietly swap in a "close enough" model. The 404 is identical whether the id never existed or simply is not served, so the error is not an existence oracle.

A content-policy refusal never reroutes. A refusal is not shopped around to a more permissive provider — that is a hard routing rule with no exceptions. If you get content_policy, the fix is the prompt.

Images are all-or-nothing. A failed, over-cap or malformed generation is a 502 and bills nothing; n above 4 on the images route is a typed 400 like n > 1 on chat. See POST /v1/images/generations.

Failover, and what the error you see means

Before any output has reached you, the gateway fails over between deployments invisibly, at zero backoff. Classes that are failover-eligible: rate_limit, auth (upstream), model_unavailable, and 5xx upstream_error. Classes that never fail over: content_policy (never, as above), context_overflow (its own typed class — reshape the request instead), and provider 4xx rejections (the request is the problem). So if a failover-eligible class reaches you, every healthy candidate was tried — x-tm-attempts says how many.

Mid-stream failures (HTTP 200 already committed)

Once your answer has started streaming, the gateway never switches providers — a provider death mid-answer becomes exactly one terminal error event inside the 200 stream, and nothing follows it (no data: [DONE], no keep-alives, no more chunks).

OpenAI surface — a real chunk envelope with finish_reason: "error" and a top-level error, so SDKs raise and naive parsers still terminate cleanly:

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "created": 1757000000,
  "model": "claude-haiku-4-5",
  "choices": [{ "index": 0, "delta": { "content": "" }, "finish_reason": "error" }],
  "error": {
    "code": "upstream_error",
    "message": "upstream failure",
    "type": "gateway_error",
    "metadata": { "error_type": "upstream_error" }
  }
}

Anthropic surface — a native error event, with the canonical class riding alongside the native type:

{ "type": "error", "error": { "type": "api_error", "message": "upstream failure", "error_type": "upstream_error" } }

On the OpenAI surface, any known usage and cost are emitted before the terminal error, so the wire stays billable-recomputable. The Anthropic wire has no legal usage slot outside message_delta; for an Anthropic-surface stream that died mid-answer, recompute from GET /v1/generation?id=<x-request-id>.

Retrying after a mid-stream error is your call — the answer never restarts on a different provider by itself.

Reading the class in code

import os
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.routerplus.com/v1", api_key=os.environ["TM_API_KEY"])

try:
    out = client.chat.completions.create(
        model="claude-haiku-4-5",
        messages=[{"role": "user", "content": "hello"}],
    )
except APIStatusError as e:
    err = e.response.json().get("error") or {}
    kind = (err.get("metadata") or {}).get("error_type") \
        or e.response.headers.get("x-tm-error-code")
    origin = e.response.headers.get("x-tm-error-origin")
    request_id = e.response.headers.get("x-request-id")
    # kind is one of the canonical classes in the table above

Retry discipline for agents

• rate_limit → wait retry-after, then retry; a capped wait can take a second try.
• email_not_verified → do not loop; ask the human to open the verify link in their email.
• insufficient_quota → do not loop; surface to a human (money). See Rate limits & spend caps.
• usage_limited → do not loop; honor retry-after once, then tell the human to contact support.
• usage_restricted → do not retry; tell the human to contact support.
• upstream_error at 5xx → one retry after ~2 s, then surface with the x-request-id. At 4xx the request itself is the problem — never blind-retry.
• upstream_error or gateway_error at 502 on the images route → one retry; nothing was billed.
• gateway_error at 503 or 504 → wait retry-after (or ~2 s), retry; nothing was billed.
• model_unavailable at 404 → pick a real id from GET /v1/models; at 502 one retry.
• content_policy, context_overflow, invalid_request, gateway_error at 400 → never blind-retry; the request must change first.