See
Long requests
for more options.
529 -
overloaded_error
: The API is temporarily overloaded.

529 errors can occur when the API experiences high traffic across all users.
In rare cases, if your organization has a sharp increase in usage, you might see 429 errors because of acceleration limits on the API. To avoid hitting acceleration limits, ramp up your traffic gradually and maintain consistent usage patterns.
The official SDK automatically retries transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the
retry-after
header when present. The SDK client accepts
max_retries
to configure or disable this behavior.


Copy page

Understand the HTTP status codes, error response shape, and request IDs the Claude API returns, and handle errors with the SDK's typed exceptions.

Copy page

HTTP errors

The API follows a predictable HTTP error code format:
400 -
invalid_request_error
: There was an issue with the format or content of your request. This error type may also be used for other 4XX status codes not listed in this section. The API also returns a 400 when usage reaches an organization or workspace
spend limit you set
, except limits on the
Claude Code workspace
, which can return a 429 instead.
401 -
authentication_error
: There's an issue with your
API key
(for example, it's malformed, revoked, or expired; see
Key expiration
).
