Claude API error types and recovery strategies

1.Sorting an error: fix the request or retry it

A failed Claude API call tells you whose problem it is before you open your own logs. The status code and the error.type string split failures into two groups. A 4xx means something is wrong with the request itself: its body, its key, its account or its size. Sending it again unchanged will fail again. A 500, 504 or 529 means something went wrong on the server side, and the same request may succeed a moment later. If you retry a 400, you loop forever. If you debug a 500 by hand, you spend an afternoon on code that was never broken.

The error body always has the same shape. It is JSON with a top-level error object that holds a type and a message, plus a request_id. The same ID comes back on every response, successful or not, in the request-id header. Log it with every failure. Support needs it when a 500 persists, and it links an application log line to the exact API call. The Python and TypeScript SDKs expose it as _request_id on response objects.

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

Two rows need a closer look. A 409 conflict_error is a 4xx that you do retry, but only after you resolve its cause. The cause is either a resource that was changed concurrently or a value that must be unique and is already in use. The classic case is two workers updating the same resource at the same moment. Retrying without making them run one after the other just reproduces the conflict. A 500 api_error is the opposite case. Nothing in your request caused it, so you back off and retry, and if it persists you open a support ticket with the request ID. New type values may appear over time, so branch on the types you know and handle unknown ones by their status group.

A single failed call is a small trace, and reading it field by field names the failure mode. The status code and error.type give the group. The message often carries the specific cause: a 400 about thinking blocks starts with the position of the offending block, such as messages.1.content.0, which points at the exact entry in your history that your code altered. Headers add more. A retry-after header means waiting will work, and its absence on a 429 together with an error.details.error_code of enforced_spend_limit_reached means it will not. The request_id ties all of this to one call, so the same ID appears in your log line, the error body and any support ticket.

Patterns across several traces separate failure modes that one trace cannot. The same call failing identically on every attempt points at the request, key or account. A 5xx that clears on the next attempt points at the server side. A 429 still failing hours later points at a spend cap, not a per-minute limit. The first split to make is where the failure sits. An error body means the integration layer failed and no output was produced, so you read the status and fix or retry. Streaming adds a catch: an error can arrive after the API has already returned a 200, so a 200 status alone does not prove the call succeeded. When the trace shows a clean 200 and the result is still wrong, the question moves to the model's output, covered in the stop-reason lesson.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message. ? }")

Sources1

2.What the SDK handles before your code sees an error

The official SDKs turn error JSON into typed exceptions. In Python, for example, a 404 surfaces as anthropic.NotFoundError. Your recovery code should branch on the exception class, never on the message text. Order matters: catch the most specific classes first, because a broad handler placed above them swallows the cases you meant to handle differently. Go doesn't follow the one-class-per-status pattern. Its SDK has a single *anthropic.Error type, and you branch on StatusCode.

The SDK is already retrying before your handler runs. It retries temporary failures (connection errors, rate limits and 5xx server errors) twice by default with exponential backoff. When the response has a retry-after header, the SDK waits as it says. The client's max_retries setting changes the retry count or turns retries off. This has two consequences for debugging. First, a retryable error that reaches your code has already been retried, so the problem lasted longer than the backoff. Second, wrapping the call in your own retry loop multiplies the SDK's attempts. Set max_retries to the number of attempts you actually want, and put your own handling on the 4xx errors, which the SDK does not retry.

Choosing a recovery strategy means picking one of four moves for each error that reaches your handler. Change the request for 400, 401, 402, 403, 404 and 413, since no repeat can succeed. Wait and let the SDK retry for a 429 that carries retry-after, a 500 or a 529. Change the transport for a 504 or a long non-streaming call, by moving to streaming or the Message Batches API. Stop and escalate when retrying is pointless: a spend-cap 429 until access resumes, or a 500 that persists, which goes to support with its request ID.

The choice also tunes max_retries. A user-facing request that must answer in seconds can lower it or set it to zero and show a fallback quickly. A nightly batch job can tolerate longer backoff and keep the default or raise it. Whatever the setting, an error that reaches your handler after the retries are spent is evidence: if a 5xx survived the backoff, log the request ID and escalate rather than looping again. A 409 is the one 4xx where your own retry makes sense, and only after you have resolved the conflict.

Sources1

3.Oversized requests and long-running calls

A 413 request_too_large is about bytes, and the model never sees the request. On the direct Claude API, Cloudflare rejects it before it reaches the API servers. Prompt wording, model choice and max_tokens make no difference. The only fix is a payload under the size limit of the endpoint you are calling. Retrying the same body cannot succeed.

A timeout is the same kind of problem, measured in time instead of bytes. A 504 timeout_error means the request timed out while processing, and the fix for long-running requests is the streaming Messages API. Idle connections cause a quieter version of the same failure. Some networks drop idle connections after a variable period, so a non-streaming call with a large max_tokens can fail or hang with no response from Anthropic at all. The SDKs guard against this in two ways. They set TCP keep-alive, and they check that a non-streaming request is not expected to run longer than 10 minutes. When that check fails, switch to streaming. The SDK can read the whole stream for you and return the same complete Message a non-streaming call would. The other option is the Message Batches API, where you poll for results instead of holding a connection open.

Sources1

4.Telling apart the 429s, and the 400 that looks like one

Several different limits share the same status codes, so the code alone doesn't tell you how to recover. Rate limits cap requests and tokens per minute, and spend limits cap monthly cost. The tiers and numbers are covered in [Rate limits, spend limits and service tiers](lesson:2.1). For debugging, what matters is the signals each response carries.

The retry-after header is the quickest way to tell them apart. A rate-limit 429 names the limit you exceeded and includes retry-after, which the SDK already honors. A rate limit can be enforced over a shorter window than a minute. For example, 60 RPM may be enforced as one request per second, so a burst can hit the limit even when the per-minute average looks fine. Acceleration limits also return 429 rate_limit_error, but they are triggered by a sharp increase in usage rather than a steady rate. The tier spend-cap 429 is the one where you must stop retrying. It has no retry-after, and its error.details.error_code is enforced_spend_limit_reached.

{
  "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"
}

There is also a 400 that looks like a request error but is really a quota. When usage reaches a spend limit you set for the organization or a workspace, the API returns 400 invalid_request_error. The message begins You have reached your specified API usage limits (or workspace API usage limits). The request body is fine, so editing it does nothing. Raising or removing the limit restores access. Limits on the Claude Code workspace are checked separately and can return a 429 with retry-after instead.

Sources23

Exam traps

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

1. 1.Every 400 invalid_request_error means the request body is malformed and must be edited.Why is that wrong?

   A spend limit you set also returns 400 invalid_request_error. The body is valid, and the fix is to raise or remove the limit.

   Covered in Telling apart the 429s, and the 400 that looks like one

2. 2.Any 429 rate_limit_error clears if you let the SDK keep retrying.Why is that wrong?

   A tier spend-cap 429 has no retry-after header and keeps failing until access resumes. Check whether error.details.error_code is enforced_spend_limit_reached.

   Covered in Telling apart the 429s, and the 400 that looks like one

3. 3.A 413 request_too_large is a capacity problem that a retry or a bigger-context model can fix.Why is that wrong?

   A 413 rejects the request for its byte size before it reaches the API servers. Only a smaller payload fixes it.

   Covered in Oversized requests and long-running calls

4. 4.A 200 response means the call succeeded, so any failure must be in the model's output.Why is that wrong?

   On a streaming response an error can occur after the API has already returned a 200, and it does not follow the usual error handling.

   Covered in Sorting an error: fix the request or retry it