Claude API Error Types, Retries and Rate Limits

1.What a Claude API error looks like

To debug a failed call, first read what the API actually returned. Every error arrives as JSON with the same shape: a top-level error object holding a machine-readable type and a human-readable message, plus a request_id that identifies this particular call. The type is the field to branch on. The message is there for people to read.

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

If you use an official SDK, you don't handle this raw JSON. The SDK raises a typed exception instead, and the class names differ by language. In Python, for example, a 404 surfaces as anthropic.NotFoundError. The Go SDK is the exception: it has a single *anthropic.Error type for every status, and you branch on StatusCode. The documentation also warns that the set of type values can grow over time, so code that string-matches error messages is fragile twice over. Catch the typed classes, and put the most specific ones first.

Sources1

2.Sorting status codes: fix the request, or wait and retry

Once you know the error type, you need a recovery strategy, and the status code mostly tells you which one. Most 4xx errors describe something about your request, key, account or resource state, so they need a change on your side. The 5xx errors, the 504 timeout and 429 rate limits describe conditions on Anthropic's side or in the network, and those can be retried. The table below lays out the codes the reference documents.

Two rows need a closer look. A 413 never reaches the model. On the direct Claude API, Cloudflare rejects the request before it gets to the API servers. The limit depends on the endpoint: 32 MB for the Messages and Token Counting APIs, 256 MB for Batch and 500 MB for Files. Retrying the same payload cannot work. A 409 is a special case among the 4xx codes. The request itself was valid, but it collided with another write, such as two workers modifying the same resource. The documented fix is to resolve the conflict and then retry.

Sources1

3.What the SDK already retries for you

Usually it doesn't. The official SDKs retry transient failures on their own. That covers connection errors, rate limits and 5xx server errors. They use exponential backoff, retry twice by default, and honour the retry-after header when the response includes one. Your handler only sees the error once those retries have run out. You can raise, lower or turn off this behaviour with max_retries on the client. Turning it off makes sense when an outer job queue already handles retries and you don't want the two layers compounding.

Timeouts are the next thing to check. The SDKs refuse to send a non-streaming Messages request that is expected to run past a 10-minute timeout. The reference also warns that some networks drop idle connections, so a long non-streaming call with a large max_tokens can fail with no response at all. For a 504, the documented fix is to change how you call the API rather than to retry harder: use the streaming Messages API, or the Message Batches API, which lets you poll for results.

Sources1

4.Three things that look like a spend or rate problem

Rate limits deserve their own section, because 429 is the one status where "just retry" is sometimes right and sometimes wrong. Messages API rate limits are measured per model class in requests per minute (RPM), input tokens per minute (ITPM) and output tokens per minute (OTPM). Going over any of them returns a 429 that says which limit you hit and includes a retry-after header telling you how long to wait. That case is transient and the SDK's retries handle it. Two details affect how you tune for it. For most models, only uncached input tokens count toward ITPM, so prompt caching raises your effective throughput. And max_tokens has no effect on OTPM, which counts only the tokens actually generated.

Reaching your usage tier's monthly spend cap also returns a 429 with type rate_limit_error, but this one has no retry-after header, and every retry fails until access resumes. That includes the SDK's automatic ones. You tell it apart by the error details.

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "You have reached your API usage limits: your organization has crossed its monthly API usage threshold, set based on your organization's API tier. You will regain access on 2026-09-01 at 00:00 UTC.",
    "details": { "error_code": "enforced_spend_limit_reached" }
  },
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG"
}

Sources2

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Every 429 is a temporary rate limit that the SDK's backoff will clear.Why is that wrong?

   A 429 caused by the tier spend cap carries no retry-after header and keeps failing until access resumes. Check error.details.error_code for enforced_spend_limit_reached.

   Covered in Three things that look like a spend or rate problem

2. 2.A 413 request_too_large is a transient server problem worth retrying.Why is that wrong?

   The request is larger than the endpoint allows, and on the direct API it is rejected before it reaches the API servers. Only a smaller request, or an endpoint with a larger limit, succeeds.

   Covered in Sorting status codes: fix the request, or wait and retry

3. 3.Parsing the error message string is a reliable way to classify API errors.Why is that wrong?

   The SDKs raise typed exceptions and the documented practice is to catch those classes, most specific first. The set of type values can also grow over time.

   Covered in What a Claude API error looks like