Error codes

This page is derived from what the code actually does; request and response headers, rate limits and balance handling are covered in Platform extensions. Two things first:

• A request passes through two layers: the gateway (authentication, rate limits, balance, body checks) and the routing layer (picking an upstream, calling it, failing over). The two layers do not produce errors in exactly the same shape, and the routing layer passes the upstream's status code through to you.
• error.code is not reliable. Gateway errors have no code; routing-layer errors have a code that sometimes equals type and sometimes is a finer value. Branch on the HTTP status plus error.type, not on code.

Every response carries an X-Request-ID header (echoed back if you sent one). Include it when you report a problem.

How to tell what happened

1. Look at the status code. 2xx is success; 4xx is usually a problem with the request and should not be retried as-is; only 429 and 5xx are worth retrying (see Retries).
2. Look at the body shape (next section). Do not assume it is always {"error": {...}}: on /v1/messages it is an Anthropic-style object, and creation-time errors on native endpoints use the vendor's own format.
3. For streaming requests, look at the stream. A failure after HTTP 200 has been sent only appears inside the stream; the status code does not change. See Failures in the middle of a stream.

Error shapes

OpenAI style (default)

/v1/chat/completions, /v1/responses, /v1/embeddings, images, audio, and every gateway-level error use this shape:

{
  "error": {
    "type": "invalid_request_error",
    "message": "unknown model: foo-1"
  }
}

There is no error.param that points at the offending parameter; read message for the detail.

Anthropic style (/v1/messages and /v1/messages/count_tokens)

{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "max_tokens is required and must be > 0" }
}

On these two endpoints, gateway errors (authentication, balance, rate limit, oversized body, suspended organization and so on) and routing-layer errors share this one shape, and type uses Anthropic's own names: 400 is invalid_request_error, 401 is authentication_error, 402 is billing_error, 403 is permission_error, 404 is not_found_error, 413 is request_too_large, 429 is rate_limit_error, 503 is overloaded_error (a type that is already an official name is kept), 504 is timeout_error, and any other 5xx is api_error.

Suspended organization or team

When the organization or team is suspended, or the key is not attached to an organization, the status is 403 and the body is the standard error object like every other gateway error, in the shape of the endpoint called (Anthropic style on /v1/messages, OpenAI style elsewhere, Google style on the Gemini endpoint). type is permission_error and message is organization suspended, team suspended or API key is not attached to an organization.

Creation-time errors on native endpoints

On native endpoints only the platform's own parameter validation uses the vendor's native format; every other error (see "Differences per endpoint" below) is still OpenAI style.

Status codes

Errors the routing layer returns for an upstream failure come from the last upstream it tried: the platform switches upstreams first, and when all fail it returns the last one's status and message. So the same 401, 402 or 403 can be either the gateway's verdict on your key or an upstream's verdict on the platform's own account. Gateway 401 messages are one of a few fixed sentences (see the table), and a gateway 402 always has type: insufficient_quota (billing_error on /v1/messages); anything that does not match is an upstream pass-through, covered below.

Where a 503 comes from

All of these are worth retrying, but only the first states how long to wait.

type values

Generated by the gateway

Generated by the routing layer

The no_upstream_available and upstream_cooling_down codes were renamed on 2026-10-19. The old names no_suppliers_available and all_vendors_cooling_down mean the same thing; if your client branches on the old code, match both the old and the new name.

Upstream errors passed through the routing layer

The status is the upstream's; message is the upstream's text (with request IDs, internal endpoint IDs and similar identifiers stripped). type depends on the endpoint and the upstream family:

context_length_exceeded and content_policy_violation only appear on embeddings and rerank. On conversational endpoints, an over-long context or a moderation block comes back as 400 with api_error or invalid_request_error; the reason is in message.

Differences per endpoint

Things to know about video and other asynchronous tasks:

• A successful create call only means the task was submitted, with HTTP 200. If the task fails later, polling still returns 200: on the DashScope endpoints output.task_status is FAILED and the reason is in output.code and output.message; on the Ark and MiniMax endpoints the upstream's task body is returned with status set to failed, and the error fields are the upstream's own.
• A task ID that is invalid or expired on poll gives the native endpoint's own 404 format; an error from the upstream call itself during a poll is an OpenAI-style 500 or 502.
• /v1/videos and /v1/videos/generations are retired and return 404 with code: endpoint_retired. Video is served only on each model's native endpoint.

GET /v1/responses/{id} locates the upstream that created the response from the ID. An ID that cannot be decoded gives 400; an upstream that cannot be found gives 404 (type: not_found). DELETE /v1/responses/{id} and POST /v1/responses/{id}/cancel need no body and no model; the gateway passes them straight through. They cost nothing, so they keep working when the balance is exhausted.

Failures in the middle of a stream

Once a stream has started, the HTTP status is already 200, so later failures can only be written into the stream. Three cases:

• The upstream errors mid-stream, the connection drops, the stream is truncated (it ended without a terminal event), or no data arrives for 4 minutes by default: an error event is emitted in the endpoint's format from the table above, then the stream ends. type is the upstream's error type, and server_error for network-level failures and truncation.
• The organization's balance runs out while the stream is in progress: the gateway cuts the stream and writes data: {"error":{"type":"insufficient_quota","message":"balance exhausted"}} followed by data: [DONE]. This frame uses the OpenAI shape on every streaming endpoint, including /v1/messages.
• You disconnect: no error event is sent.

How to handle it: treat "no normal terminator received" as a failure. For Chat Completions that means the last chunk has no finish_reason or an error frame appeared; for Anthropic, no message_stop; for Responses, no response.completed. On a mid-stream failure the part already generated is still billed at the upstream's actual usage.

If the failure happens before the first byte, the platform switches upstreams automatically. If one succeeds you get a normal response; only when all fail do you get a JSON error with a status code.

Retries

import random, time

RETRYABLE = {408, 429, 500, 502, 503, 504}

def call_with_retry(send, tries=4):
    for i in range(tries):
        resp = send()
        if resp.status_code not in RETRYABLE or i == tries - 1:
            return resp
        wait = float(resp.headers.get("Retry-After", 2 ** i))
        time.sleep(wait + random.random())

Duplicate calls and double billing

• The platform has no idempotency key and does not deduplicate by request content.
• When the platform switches upstreams internally, only the attempt that finally succeeds is billed; failed attempts are not. You see one success or one error.
• A retry from your side is a new request. If the earlier one actually succeeded and only the response failed to reach you (client timeout, dropped connection), the retry produces a second generation and a second charge. That is tolerable for conversational requests; it is not for video creation: after a timeout, 502 or dropped connection on a create call, first check whether the task was created before creating another, or you end up with two tasks and two charges.
• Do not retry a stream that failed midway as if it were the same generation: the output already delivered has been billed, and starting over bills again. To continue, put what you received into the context and send a new request.
• Non-streaming requests face two related time limits: the gateway disconnects and returns 502 if it has no response headers after 120 seconds, and the routing layer's total budget for an upstream call is 10 minutes non-streaming and 5 minutes streaming. Use stream: true for requests that may take longer than two minutes.