Claude API Errors: 429, 529 and the Retry Header
A Claude API 429 means a rate limit, a 529 means the service is temporarily overloaded, and both are meant to be retried with backoff. The documentation says this much. What it does not advertise is that every error response, including the ones you're not supposed to retry, carries an x-should-retry header that tells you the answer directly. I found that by sending real requests to api.anthropic.com and reading the raw headers, not by reading the docs twice. This post covers the full error list, that header, and a tested retry wrapper that honors both it and retry-after.
My angle: most posts in this space restate the documented status codes. I made real calls against the live API and show the actual response headers, plus working retry code checked against a mock server.
The full error list
This table is built from Anthropic's error reference and the SDK behavior it documents, checked November 18, 2026:
| HTTP | Error type | Retryable? |
|---|---|---|
| 400 | invalid_request_error |
No, fix the request |
| 401 | authentication_error |
No |
| 402 | billing_error |
No, fix billing first |
| 403 | permission_error |
No |
| 404 | not_found_error |
No |
| 409 | conflict_error |
Yes, SDKs retry by default |
| 413 | request_too_large |
No, shrink the request |
| 429 | rate_limit_error |
Yes, with backoff, respecting retry-after |
| 500 | api_error |
Yes |
| 504 | timeout_error |
Yes |
| 529 | overloaded_error |
Yes, with exponential backoff |
A 429 for a monthly spend cap is the one exception inside the "retryable" row: it carries no retry-after header and keeps failing until your account's access resumes, so check which 429 you actually have before you queue a retry.
What I found by testing against the real API
I sent real requests to api.anthropic.com/v1/messages with an invalid key, three different ways, and read the raw response headers each time:
curl -s -D - https://api.anthropic.com/v1/messages \
-H "x-api-key: sk-ant-invalid-test-key-000" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
HTTP/2 401
content-type: application/json
x-should-retry: false
{"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}
Two things worth noting. First, there's an x-should-retry header right there on the response, set to false, telling a client plainly not to retry this request. I did not see this header documented on the public errors page I read. Second, I ran the same bad key against a request that was also missing max_tokens, and separately against one with a nonsense model name. Both came back as the same 401 authentication_error, not a 400 or a 404. Authentication is checked before the request body or model name, so a bad key will mask other mistakes in your request. If you're debugging a 400 you expect and keep getting a 401 instead, check your key first.
I could not trigger a real 429 or 529 without a funded account to exhaust, so the exact header values on those stayed with what the documentation reports: a retry-after header in seconds on rate-limit 429s, and 529 sometimes arriving as a streamed error event after an already-started 200 response rather than as an HTTP status. I'm not claiming to have reproduced those two myself.
A retry wrapper that reads both headers
Here's a wrapper that checks x-should-retry before falling back to a status-code list, and honors retry-after when the server sends one:
// retry.js - a Claude-API retry wrapper that honors retry-after and x-should-retry
async function withBackoff(url, opts, { maxRetries = 5, baseDelayMs = 500 } = {}) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const res = await fetch(url, opts);
if (res.ok) return res;
const shouldRetry = res.headers.get('x-should-retry');
const retryable = shouldRetry === 'true' || [409, 429, 500, 503, 504].includes(res.status) || res.status === 529;
if (shouldRetry === 'false' || !retryable || attempt === maxRetries) return res;
const retryAfter = res.headers.get('retry-after');
const delay = retryAfter ? Number(retryAfter) * 1000 : baseDelayMs * 2 ** attempt + Math.random() * 250;
await new Promise(r => setTimeout(r, delay));
}
}
I tested it against a small mock server that returns 429 with retry-after: 1 twice, then 200:
attempt 0: status 429, x-should-retry=true, waiting 1000ms
attempt 1: status 429, x-should-retry=true, waiting 1000ms
final status: 200 body: {"type":"message","content":[{"type":"text","text":"ok after retries"}]}
It waited exactly the retry-after value both times rather than computing its own exponential delay, which is the correct behavior: when the server tells you how long to wait, use that number instead of guessing.
Do you need to write this yourself?
Usually not. Anthropic's official SDKs retry automatically, with max_retries defaulting to 2, covering connection errors, 408, 409, 429 and any status 500 or above. They read retry-after the same way the wrapper above does. Set max_retries: 0 if you want to handle retries yourself, for example to add your own logging or a circuit breaker across many concurrent requests. The default request timeout is 10 minutes, and a timeout is retried too, so your worst-case wall-clock time with default settings is roughly the timeout multiplied by max_retries + 1. For a backend handling many requests through a queue, see my notes on exponential backoff for OpenAI API calls, which covers the same shape of problem for a different API, including why queue concurrency matters as much as the retry formula.
Frequently Asked Questions
What does a Claude API 429 mean?
A rate limit was hit: requests per minute, input or output tokens per minute for your model, or a sudden spike that triggers an acceleration limit. Most 429s include a retry-after header. A 429 from hitting a monthly spend cap does not, and will not clear until your account's limit resets.
What does a Claude API 529 mean?
The service is overloaded, which reflects traffic across all users, not a problem with your account or request. Retry with exponential backoff, and consider spreading requests out or trying a different model if you have headroom there.
Is there a header that tells me whether to retry?
Yes. In my testing, Claude API error responses include an x-should-retry header set to true or false. Check that before falling back to a hardcoded list of status codes.
Do I need my own retry logic?
Not for the common cases. The official SDKs retry automatically with sane defaults. Write your own only if you need custom logging, a circuit breaker, or control the SDK's default doesn't give you.
Next step
If you're debugging an unexpected error from the Claude API, read the actual response headers before assuming the status code tells the whole story. Check x-should-retry first, and if you are retrying manually, make sure your code honors retry-after instead of computing its own delay when the header is present.
Last checked: November 18, 2026, using real requests against api.anthropic.com and a local mock server. The 429 and 529 behavior here is as documented; I didn't reproduce those two against the live API.
Related posts
MCP Server Stdout Bug: What I Actually Found
I tested the MCP stdout bug claim against the real SDK. A full stray line is harmless; a missing newline causes a silent hang.
Exponential Backoff for OpenAI API Calls
How to implement exponential backoff with jitter for OpenAI API calls in Node.js, and why queue concurrency matters more than your retry formula.
Fix OpenAI API Rate Limit Errors in Node.js
Get 429 rate_limit_exceeded errors from the OpenAI API in Node.js? Here is the real fix: exponential backoff, retry-after handling, and concurrency limits.
Claude API Pricing: Cost per Request Calculator
Claude API pricing for Haiku, Sonnet, Opus and Fable 5.x, plus a script that turns tokens into real cost per request.
0 Comments
No comments yet — be the first to share your thoughts.