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

Four 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 own error body is never relayed. The provider's HTTP status is in x-tm-upstream-status when it answered.
• 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 error.code, metadata.error_type, or the HTTP status — not on error.type, which is a generic string. The one exception is out-of-credits: there both code and type are insufficient_quota, byte-matching OpenAI's own wire so OpenAI SDKs recognize it natively.
• 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.

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.

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":"deepseek/deepseek-v4-flash","messages":[{"role":"user","content":[{"type":"text","text":"What is in this picture?"},{"type":"image_url","image_url":{"url":"https://example.com/cat.png"}}]}]}'

{
  "error": {
    "code": "invalid_request",
    "message": "messages[0].content[1]: model \"deepseek/deepseek-v4-flash\" does not take image input; it takes text",
    "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, retry once.
• 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.

A video that fails

A video job ends failed without an HTTP error: POST /v1/videos answered 200 when the job was accepted, and the failure arrives later, on GET /v1/videos/{id}, as status: "failed" with error: {code, message}. The code is one of video_generation_failed, content_policy_violation, video_cancelled, video_expired or video_timeout. A failed job costs nothing; content_policy_violation means change the prompt. See POST /v1/videos.