Errors

When to use this pageCopy Anchor Link

A request failed and you want to know why, whether to retry it, or what to send to support. Limits and backoff are on Rate limits.

Error formatCopy Anchor Link

Errors use the format of the API you called, with the same HTTP status on both.

/v1/* (Anthropic format):

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: anthropic/no-such-model"
  },
  "request_id": "0b1c6f2e-5d4a-4f7e-9a51-3f0e8d2c7b19"
}

/openai/v1/* (OpenAI format):

{
  "error": {
    "message": "The model `anthropic/no-such-model` does not exist or you do not have access to it.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found"
  }
}

The Anthropic and OpenAI SDKs turn these into their own error classes (for example NotFoundError), so you rarely parse them yourself. See the error handling sample in curl, Node.js or Python.

Status codesCopy Anchor Link

The OpenAI-compatible API returns 503 where the Anthropic format returns 529, because OpenAI clients don't know 529. Its 404 for a model also sets "param": "model".

None of these errors is charged. See How billing works.

Messages you may seeCopy Anchor Link

A 400 that the model itself returns (for example a parameter the model doesn't accept) carries the model's own message.

Paths that don't existCopy Anchor Link

A path the gateway doesn't serve, such as /v1/messages/batches or /v1/files, returns 404 in a plain format, not in either envelope:

{ "statusCode": 404, "message": "Cannot POST /v1/messages/batches" }

Errors during a streamCopy Anchor Link

Once a streamed response has started, the HTTP status is already 200. If something fails after that, the gateway sends one error event and ends the stream. The request is marked Failed in Usage and isn't charged.

Anthropic format: an error event, with no message_stop after it.

event: error
data: {"type":"error","error":{"type":"api_error","message":"Upstream provider error"}}

OpenAI format: a chunk with an error object, then [DONE].

data: {"error":{"message":"Upstream provider error","type":"server_error","param":null,"code":null}}

data: [DONE]

The error types are the same as in the table above. The Anthropic and OpenAI SDKs raise an APIError (or a subclass) when they read it, and don't retry it: send the request again yourself if you want to.

If your client disconnects mid-stream, there is no error event; see interrupted streams.

Request idsCopy Anchor Link

Two response headers identify a request:

• In the Anthropic format, the error body's request_id is the x-request-id.
• On the OpenAI-compatible API, a completion's id is chatcmpl- followed by its request-id.
• The Anthropic SDKs expose request-id (message._request_id, and error.request_id in Python or error.requestID in Node). For a refused request there is no request-id, so read x-request-id from the error's response headers.
• The OpenAI SDKs expose x-request-id (completion._request_id, error.request_id in Python, error.requestID in Node).

Contact supportCopy Anchor Link

Email support@ezat.io with:

1. The request-id, if the response had one, and the x-request-id.
2. The time of the request (with its time zone), the model, and which API you called (/v1/messages or /openai/v1/chat/completions).
3. The HTTP status and the error message.

Never send your API key. Request and response bodies aren't stored, so include the parts of the request that matter.

For AI agentsCopy Anchor Link

1. Read the HTTP status first, then error.type (Anthropic format) or error.code (OpenAI format).
2. Don't retry 400, 401, 402, 403, 404 or 413. Fix the request, tell the user to check the key or add credit at https://router.ezat.io/billing, or pick a model from GET https://api.router.ezat.io/v1/models.
3. Retry 429, 500, 529 and 503 with exponential backoff, waiting at least the retry-after seconds when the header is there. The official Anthropic and OpenAI SDKs already do this, twice by default.
4. For a 504 timeout_error, resend with "stream": true instead of retrying as is.
5. A stream can end with an error event (Anthropic) or an error chunk (OpenAI) after a 200. Treat it like a 500.
6. When reporting a problem, give the user the request-id and x-request-id headers and the time. Never include the API key.