If you’re seeing 529 overloaded_error from the Claude API, the short version is: it’s not you. Anthropic’s servers are saturated, your request was never processed, and the same call will usually go through on a retry.

The longer version matters if you’re deciding what to change in your code. A 529 and a 429 look similar in a log and need opposite responses, and there’s a good chance your SDK is already handling 529s without you knowing.

Everything below is checked against Anthropic’s API errors reference, rate limits, and Claude Code model configuration docs, all re-read in early August 2026. We haven’t reproduced a 529 on demand, because you can’t summon one. What we did test on our own machine is Claude Code’s fallback behavior, by pinning the primary to a retired model — see the run below. Everything else here is documentation, and labeled as such.

Key takeaways

• 529 is overloaded_error — Anthropic’s capacity, not your account. Retry it.
• 429 is rate_limit_error — your account hit a limit. Retrying harder makes it worse.
• The official SDKs already retry both, twice by default, with exponential backoff.
• A sharp traffic ramp can produce 429s from acceleration limits even under your quota.
• Claude Code has a one-flag answer: --fallback-model, which fires on overload but never on a 429.
• A 529-class failure can arrive mid-stream after a 200, where your error handler won’t see it.

What is error 529 in the Claude API?

529 is the HTTP status Anthropic returns for overloaded_error, defined in the API errors reference as “The API is temporarily overloaded.”

Nothing about your request is wrong. It was rejected before processing because there wasn’t capacity to serve it, which is why the identical payload usually succeeds seconds later. Anthropic’s own note is explicit that this is a shared-capacity condition: 529s “can occur when the API experiences high traffic across all users.”

That’s the whole diagnosis. There’s one exception, and it’s closed to new customers: Anthropic’s Priority Tier prioritizes an organization’s requests over everyone else’s, which the docs say “helps minimize ‘server overloaded’ errors, even during peak times.” But capacity commitments are no longer sold, existing ones expire at contract end, and the tier doesn’t cover Claude Opus 5 or Sonnet 5 anyway. So on the current flagship models, nobody is buying their way out of 529s. All you control is retry strategy and, if 529s are frequent enough to hurt, a different model or a different time of day.

529 vs 429: same log line, opposite fix

Both are transient and both are retryable, but they mean different things and reward different behavior.

	429	529
Error type	rate_limit_error	overloaded_error
Whose limit	Yours — your account hit a rate limit	Anthropic’s — shared capacity is saturated
Right response	Slow down; check retry-after and the anthropic-ratelimit-* headers	Retry with backoff; consider another model
Retrying aggressively	Makes it worse	Reasonable, within limits

There’s a wrinkle here that makes 429s look like 529s. Anthropic’s docs warn that “in rare cases”, an organization with a sharp increase in usage may see 429s “because of acceleration limits on the API”, a throttle on how fast you ramp that is distinct from your steady-state quota. The guidance is to “ramp up your traffic gradually and maintain consistent usage patterns.”

So if 429s appear right after you turned on a new batch job, the fix probably isn’t a tier upgrade. It’s a slower ramp.

One more distinction that a lot of writing collapses: 500 api_error and 504 timeout_error are not 529s. The SDKs retry all three, but only two deserve it. 500 means something broke internally, and the docs tell you to retry with backoff. 504 means your request was still processing when it timed out, and an identical retry just spends the same ten minutes again; the docs point at streaming or the Batches API instead.

Because 500 and 529 both land in the 5xx bucket, most SDKs raise the same exception class for both — InternalServerError in Python, for instance. If you need to branch on which one you got, read error.type from the response body, not an attribute on the exception object. It carries the string overloaded_error or api_error, so you don’t have to match on the message text.

Your SDK probably already retries 529

If you’re using an official Anthropic SDK on default settings, your 529s are already being retried twice with exponential backoff. Most 529 tutorials skip this, which is why so many of them hand you a backoff decorator you already have.

Anthropic’s docs state that the official SDKs “automatically retry 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.” Every SDK client takes a max-retries option to tune or disable it.

Read that closely, because it covers a lot: connection errors, 429s, and 5xx, which includes 529. Out of the box, a 529 becomes three attempts with backoff before you ever see an exception. If you’re about to add an exponential-backoff decorator, check first whether you’re rebuilding something you already have.

What usually helps instead:

• Raise the retry count rather than writing your own loop. Two retries is a default, not a ceiling.
• Know the timeout interaction. The default client timeout is 10 minutes, and timeouts are themselves retried — so worst-case wall-clock is roughly the timeout times the number of attempts. If you need a hard deadline, set both deliberately.
• Watch the units. The timeout is in seconds in the Python SDK and in milliseconds in TypeScript. A timeout: 30 in TypeScript is 30 milliseconds, not 30 seconds.

Write your own retry logic when you need something the built-in behavior doesn’t do — a jittered backoff to avoid a thundering herd, a circuit breaker, a queue that sheds load, or a fallback to a different model. Not because you need retries at all.

Should you switch models on a 529?

Yes, if availability matters more to you than using one specific model. Anthropic ships model fallback as a first-class feature in Claude Code, built specifically for when the primary model is overloaded, which tells you what they expect you to do about a 529.

What Anthropic doesn’t publish is per-model capacity. “Just use Haiku, it’s less busy” is a guess, and you’ll see it stated as fact all over this topic. The honest version is simpler: a second model is a second pool of capacity, and that’s the entire argument for switching.

That’s a real tradeoff, not a free win: a fallback model is a different model, with different output. It fits a coding agent that just needs to keep moving, and fits badly where consistency matters — evals, anything user-facing where quality is the product, or a pipeline whose downstream steps assume a particular model’s behavior.

Claude Code: use --fallback-model

If the 529s are hitting you in Claude Code rather than in your own API calls, there’s a flag for exactly this and no code to write.

Anthropic’s CLI reference describes --fallback-model as enabling “automatic fallback to the specified model(s) when the primary model is overloaded or not available.” It takes a comma-separated list, tried in order:

claude --fallback-model sonnet,haiku

If you want it permanently rather than per-invocation, there’s a fallbackModel setting that persists across sessions; the flag overrides it when both are present.

Three details from the model configuration docs that decide whether this actually helps you:

• It fires on overload, not on rate limits. The docs list what never triggers a switch: “Authentication, billing, rate-limit, request-size, and transport errors.” So this is a 529 answer and explicitly not a 429 answer — the same split as the rest of this article.
• The switch lasts one turn. Your next message tries the primary model again. That’s the opposite of Claude Code’s content-based fallback (the safety-classifier one), where the session stays on the fallback until you run /model. Two different features with similar names.
• You get no confirmation that it’s configured. Startup doesn’t confirm the chain and /status doesn’t show it. The notice when a switch happens is the first visible sign it was ever on. Chains cap at three models.

We forced a fallback to see what it actually does

You can’t summon a 529, but you can make the primary model unreachable, which the docs treat as the same trigger. We pinned the primary to claude-3-5-haiku-20241022 — retired on February 19, 2026 — on Claude Code 2.1.220, macOS, August 2026.

Without a fallback, it just fails:

claude --model claude-3-5-haiku-20241022 -p "Reply with exactly: OK"
# There's an issue with the selected model (claude-3-5-haiku-20241022).
# It may not exist or you may not have access to it.

Add the flag and the same command succeeds:

claude --model claude-3-5-haiku-20241022 --fallback-model sonnet -p "Reply with exactly: OK"
# ⚠ Claude 3.5 Haiku was retired on February 19, 2026. Consider switching to a newer model.
# OK

Adding --output-format json confirms where the work went: modelUsage attributed every token to claude-sonnet-5 and nothing to the pinned primary. The chain worked exactly as documented.

Run it interactively and the notice is unmissable:

That highlighted line is the whole user-facing signal: “Switched to Sonnet 5 because Haiku 3.5 is not available.” Note what it doesn’t say — nothing about 529s or overload, because the notice reports the switch, not the cause.

One thing surprised us, and it sharpens the warning above. That notice only exists in the interactive TUI. In headless mode (-p), nothing in stdout says a fallback happened. The startup deprecation line appears with or without the flag, so it proves nothing, and we could only confirm the switch by reading modelUsage out of the JSON. If you run Claude Code in CI with a fallback chain, your logs won’t tell you which model answered.

Honest limit: this exercises the unavailable branch of the trigger, not a live 529. Anthropic’s docs group them under the same condition, but we haven’t watched this fire against a real overload.

Our Claude Code review covers the rest of the CLI in depth.

Why doesn’t my error handler catch 529s when streaming?

Because a 529 can arrive inside a stream that already returned HTTP 200 — and when it does, neither your try/except nor the SDK’s automatic retry will fire.

The streaming docs name this case directly: “during periods of high usage, you may receive an overloaded_error, which would normally correspond to an HTTP 529 in a non-streaming context.” It arrives as an event:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

When you’re streaming, the API returns a 200 and then starts sending events. If something goes wrong after that point, Anthropic’s docs are explicit that “error handling doesn’t follow these standard mechanisms.”

Your try/except around the request never fires. The SDK’s automatic retry never fires either, because as far as the transport is concerned the request worked. What you get is a stream that stops early, and if you’re not inspecting stream events you may not notice at all. You just see a truncated response.

If you stream, and you should for anything long-running, handle error events explicitly, separately from your request-level error handling. This is the single most common gap between code that works in testing and code that degrades quietly in production.

Is Claude down, or is it just you?

Before you spend an afternoon on retry tuning, check whether you’re debugging a real incident.

A burst of 529s across every request usually means an incident, and a scattered few under load usually means normal contention. Anthropic publishes live service status, and we mirror it alongside the other AI dev tools on our Claude Code status board so you can tell an outage from a local problem without hunting for the right status page.

Two things to capture while you’re there. Every API response carries a request-id header (the Python and TypeScript SDKs expose it as _request_id), and it’s what Anthropic support asks for first. And if 529s are frequent enough to be a cost problem rather than a reliability one, retries multiply token spend on the attempts that do land. Our guide to cutting LLM API costs covers the levers.

What should you do about a 529, in order?

Most people stop after the second step:

1. Confirm it’s a 529, not a 429. They need opposite responses, and the acceleration-limit case makes a 429 look like a capacity problem when it isn’t.
2. Check your SDK’s retry configuration before writing anything. Two retries with backoff is already there. Raising that number is a one-line change.
3. Add a model fallback if availability beats model consistency for your use case. In Claude Code that’s --fallback-model; in your own code it’s a branch in the exception handler.
4. Handle stream error events separately. They bypass request-level error handling entirely.
5. Check the status page before assuming the problem is yours.

What you almost certainly don’t need is a third-party proxy sitting between you and the API. That’s the recommendation at the end of most articles on this error, and most of those articles are published by companies selling one. A 529 is a retry, a model switch, and a status check.

See also: Claude Code review · The complete guide to AI coding assistants · Claude Code status · All developer guides

• claude
• anthropic
• api-errors
• ai-coding-assistants

Frequently asked questions

What does error 529 mean in the Claude API?

529 is overloaded_error, and Anthropic's docs define it as "The API is temporarily overloaded." It's a capacity signal, not a problem with your request or your account. The same request that failed will usually succeed on a retry a few seconds later. Anthropic notes that 529s happen when the API sees high traffic across all users, so it isn't tied to your own usage.

What is the difference between a 429 and a 529 from Claude?

A 429 is rate_limit_error: your account hit a limit, so the fix is on your side, either slowing down or raising your tier. A 529 is overloaded_error: Anthropic's capacity is saturated, so the fix is to retry. One nuance to know is that Anthropic's docs say that in rare cases a sharp increase in your own usage can produce 429s from acceleration limits, even below your steady-state quota. If 429s appear right after you scale up traffic, ramp more gradually rather than assuming your quota is wrong.

Do I need to write my own retry logic for 529 errors?

Often not. Anthropic's docs state that the official SDKs automatically retry transient failures (connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the retry-after header when present. Every SDK client exposes a max-retries option to change or disable that. Before writing a backoff helper, check whether you're re-implementing behavior you already have, then raise the retry count if two isn't enough.

How do I stop Claude Code from failing when the model is overloaded?

Use the --fallback-model flag, which takes a comma-separated list tried in order, for example: claude --fallback-model sonnet,haiku. Anthropic's docs say Claude Code switches when the primary model is overloaded, unavailable, or returns another non-retryable server error, and that rate-limit errors never trigger a switch, so this is a 529 fix and not a 429 fix. Chains are capped at three models, and the switch lasts for the current turn only. There's also a fallbackModel setting if you want the chain to persist across sessions.