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.
  • 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:

JSON
{
  "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.