Claude API 529 overloaded_error — what it is and how to ride it out

529 is the one Claude error your code didn't cause: Anthropic itself is overloaded. You can't fix it — you can only absorb it gracefully. That means patient retries, a fallback model, and never amplifying the incident with instant-retry storms.

The error

response (HTTP 529)

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

Causes and fixes at a glance

Cause	Fix
Provider-side saturation (launch days, regional incidents)	Backoff with jitter; check the provider status page instead of redeploying your app.
Your burst landing during a soft incident	Spread batch jobs; a 10-minute delay usually clears it.

Retry like a good citizen

Treat 529 like 429-without-retry-after: exponential backoff starting at ~2s, jitter, cap at 30–60s, give up after ~5 attempts and queue the work. The backoff snippet from our 429 guide handles 529 in the same branch.

Fail over instead of failing down

For latency-sensitive paths, define a fallback: same family (Sonnet → Haiku) keeps behavior close; cross-provider (Claude → Gemini) survives a whole-provider incident. On an OpenAI-compatible endpoint that's a one-string change:

failover.py

PREFERRED = ["claude-sonnet-4-6", "claude-haiku-4-5", "gemini-2-5-flash"]

def complete(messages):
    last = None
    for model in PREFERRED:
        try:
            return client.chat.completions.create(
                model=model, messages=messages, max_tokens=800)
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise
            last = e          # saturated — try the next tier
    raise last

If you're calling through Kunavo

Kunavo routes Claude across more than one upstream path and its multi-model catalog makes cross-provider failover a model-string change on the same key and wallet — the failover pattern above needs no second account. 529s that reach you are still never billed.

FAQ

Is a 529 my fault?

No. It's provider-side capacity. Your only responsibilities are not amplifying it (backoff, jitter) and having somewhere to fail over if the incident outlives your latency budget.

529 vs 429 — what's the difference?

429 means you crossed your limits (server is fine); 529 means the server itself is overloaded (your quota is fine). Both are retryable; only 429 comes with a retry-after hint.

More error semantics live in the error reference; getting a key takes a minute via sign up and the authentication docs.