Skip to content
← Changelog
2.2.132
Fix

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.

Terminal: a key that does not exist on /v1/messages answered as an Anthropic authentication_error, the headers of a 429 on /v1/messages, and a Claude refusal on chat completions with finish_reason content_filter
HTTP statuserror.type
401authentication_error
403permission_error
404not_found_error
413request_too_large
429rate_limit_error
503, model temporarily unavailableoverloaded_error
Any other 4xx, such as 400, 402 or 422invalid_request_error
500, and 503 for any other server errorapi_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.
Table: each HTTP status and the Anthropic error type /v1/messages answers with

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.