Fix: Anthropic 529 "Overloaded" — What overloaded_error Means and How to Handle It

TL;DR — HTTP 529 with {"type":"overloaded_error","message":"Overloaded"} means Anthropic's service is temporarily saturated. It is not a rate limit (that's 429), not a billing problem, and not caused by your request. Nothing on your side is broken, so there is nothing on your side to fix — the correct response is retry with exponential backoff and jitter, and for agent workloads, failover to another model or provider when the burst outlasts your patience. 529s tend to arrive in clusters during demand spikes and pass on their own.

The error

HTTP 529
{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  }
}

In Claude Code and other Anthropic-backed tools it surfaces as a visible "API overloaded" style failure or an automatic retry pause; through SDKs it raises the corresponding API error class.

529 vs 429 vs 500 — read the status precisely

| Status | Type | Whose problem | Correct response | |--------|------|---------------|------------------| | 429 | rate_limit_error | Your account's request/token rate | Back off; check the retry-after header; consider a higher tier | | 529 | overloaded_error | Provider capacity, global | Backoff with jitter; failover if persistent | | 500 | api_error | Provider internal fault | Retry a couple of times; report if reproducible |

The practical difference between 429 and 529: a 429 responds to your behavior (you can spend or throttle your way out of it), while a 529 does not — during a demand spike, sending less traffic yourself doesn't make the spike end sooner.

Why it comes in bursts

Overload is a fleet-level condition: model launches, big product moments, and peak coding hours produce demand spikes, and during a spike some fraction of requests get shed. Which is why the pattern is characteristic — several 529s in a row, then normal service, rather than a steady background trickle. Long-context requests are the expensive ones to serve, so heavy agent workloads tend to notice overload windows first.

Correct retry strategy

Exponential backoff with jitter, and a cap on attempts:

import time, random

def call_with_backoff(fn, max_attempts=5, base=2.0):
    for attempt in range(max_attempts):
        try:
            return fn()
        except OverloadedError:
            if attempt == max_attempts - 1:
                raise
            time.sleep(base ** attempt + random.uniform(0, 1))

The jitter matters: if every client that got shed retries on the same schedule, the retries themselves arrive as a synchronized wave — the thundering-herd effect — prolonging the overload. Official SDKs already implement retry-with-backoff for 529s; if you use one, resist stacking a second aggressive retry loop on top.

Also worth doing during a burst:

• Pause parallel agents. Five concurrent sessions retrying into an overloaded service is the worst version of you as a client.
• Don't switch API keys. 529 is not account-scoped; a fresh key meets the same fleet.

The failover question

For interactive coding, the real cost of a 529 burst is minutes of stalled flow. Backoff is correct but passive. The active answer is having somewhere else to send the request: a comparable model on another provider, selected automatically when the primary returns repeated 529s. That requires your tooling to treat the model as a routing decision rather than a constant — the case for that architecture, overload aside, is what a router API should handle for you, and which models make sensible fallbacks for coding.

If you run a single provider by choice, at minimum make 529 handling visible: an agent that silently retries for ten minutes looks identical to a hung agent.

Prevention (what little there is)

You cannot prevent provider overload — you can only shape your exposure:

• Keep requests lean (smaller context = cheaper to serve = shed less often, and cheaper to retry).
• Schedule bulk/batch jobs off peak hours; interactive sessions deserve the contested capacity more than your overnight refactor script does.
• Watch the provider status page during sustained incidents rather than debugging your own stack.

Part of the LLM API Error Reference — errors indexed by their exact strings.