Claude API 529 overloaded_error — Meaning and Correct Handling

Retry without making the outage worse

Treat 529 as “429 without Retry-After.” Use exponential backoff starting at about 2 seconds, with jitter, capped at 30–60 seconds; give up after roughly five attempts and move the work to a queue. The part that matters is the jitter. Without it, every client comes back at the same moment and prolongs the congestion you were trying to escape.

Redirect instead of dropping

Prepare a fallback chain for latency-sensitive paths. With an OpenAI-compatible endpoint, you change only one string — there is no need to add an SDK or create another account:

PREFERRED = ["claude-sonnet-5", "claude-haiku-4-5", "gpt-5-6-terra"]

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          # 過負荷 — 次の候補へ
    raise last

Question your own code last

If only a specific request type returns 529 while other calls at the same time succeed, it is not a system-wide outage. Check whether that path is sending an unusually large prompt or firing requests in a tight loop. Conversely, if all calls return 529 at once and then recover on their own, the cause is capacity. In that case, fix retries and fallbacks, not the refactoring.

Is 529 my fault?

No. It is a capacity issue on the provider’s side. Your responsibilities are limited to two things — not amplifying the outage (backoff and jitter), and having somewhere to redirect requests when the outage exceeds your latency budget.

What is the difference between 529 and 429?

429 means you exceeded your own limit while the server is healthy. 529 means the server is overloaded while your limit and balance are healthy. Both can be retried, but only 429 includes a Retry-After hint.

How long does 529 usually last?

It cannot be predicted or guaranteed. That is why the correct approach is capped backoff plus a queue, not hard-coding a fixed wait time. If the path has a latency budget, fallback should take over instead of waiting.

Are calls that fail with 529 billed?

Not through Kunavo. Requests that end in an error are not billable. With a direct contract, follow each provider’s billing rules.