Anthropic error types your client can act on
A client reading error.type on /v1/messages could not tell a bad key from a server fault; now an error there is an Anthropic error with the type its status means, and a 429 from a request or token limit says how long to wait.
We changed how /v1/messages answers an error. An error now comes back in Anthropic's error format, with the error.type its HTTP status means, so a client that reads error.type can tell a bad key from a server fault and retry only what is worth retrying. A 429 from a request or token limit tells you how long to wait, a Claude refusal on chat completions now carries its reason, and a model that does not exist answers 404.
Errors in Anthropic's format on /v1/messages
An error from /v1/messages used to come back in the OpenAI shape, often typed api_error, so error.type did not say what went wrong. An error response with status 400 or higher is now:
{"error":{"message":"Invalid API Key","type":"authentication_error"},"type":"error"}That is what production answers today for a key that does not exist. The request id is no longer inside message; it is in the X-Apertis-Request-Id response header.

| HTTP status | error.type |
|---|---|
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 503, model temporarily unavailable | overloaded_error |
| Any other 4xx, such as 400, 402 or 422 | invalid_request_error |
| 500, and 503 for any other server error | api_error |
A server error other than 500, such as a 502 or 504, now answers 503. A successful response and a stream that has started are passed through unchanged, and an error already in Anthropic's format keeps its type, with only our request id removed from its message. /v1/chat/completions keeps its OpenAI error format.
On /v1/messages, two cases also changed status:
- A model outside your key's model list answers 404
not_found_error, where it answered 403, and so does a model your group does not offer, where it answered 503 when another group offers it. - An error found before the request leaves Apertis, such as a missing
max_tokens, keeps its own message. It used to read as if the upstream provider had rejected the request.

A 429 tells you how long to wait
A request turned away by a per-key or per-model request limit, or by a token limit, answers 429 with a Retry-After header, a whole number of seconds. A request limit also sends x-ratelimit-limit-requests, x-ratelimit-remaining-requests and x-ratelimit-reset-requests; a token limit sends the same three ending in -tokens. remaining is 0, and reset is the same wait as Retry-After. On /v1/messages, a per-model request limit or a token limit answers a rate_limit_error.
A Claude refusal keeps its reason on chat completions
When a Claude model declines a request on /v1/chat/completions, the choice, which ends with finish_reason: "content_filter", now also carries the reason in message.refusal, or delta.refusal when streaming. When the model gives no explanation, the reason is The model declined to respond.
A model that does not exist answers 404
GET /v1/models/{id} for a model that does not exist answers 404 with error.code model_not_found. It answered 200 with an error in the body, which a client read as success.
Your system prompt is sent as written
We send the system prompt in your request as written; by default nothing rewrites it.
The error codes and headers are on Error codes, and the request format on Messages.