HTTP errors

Our API follows a predictable HTTP error code format:

  • 400 - invalid_request_error: There was an issue with the format or content of your request. We may also use this error type for other 4XX status codes not listed below.
  • 401 - authentication_error: There’s an issue with your API key.
  • 403 - permission_error: Your API key does not have permission to use the specified resource.
  • 404 - not_found_error: The requested resource was not found.
  • 413 - request_too_large: Request exceeds the maximum allowed number of bytes.
  • 429 - rate_limit_error: Your account has hit a rate limit.
  • 500 - api_error: An unexpected error has occurred internal to Anthropic’s systems.
  • 529 - overloaded_error: Anthropic’s API is temporarily overloaded.

When receiving a streaming response via SSE, it’s possible that an error can occur after returning a 200 response, in which case error handling wouldn’t follow these standard mechanisms.

Error shapes

Errors are always returned as JSON, with a top-level error object that always includes a type and message value. For example:

  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."

In accordance with our versioning policy, we may expand the values within these objects, and it is possible that the type values will grow over time.

Request id

Every API response includes a unique request-id header. This header contains a value such as req_018EeWyXxfu5pfWkrYcMdjWG. When contacting support about a specific request, please include this ID to help us quickly resolve your issue.