Claude API 529 overloaded_error — what it means and how to handle it

Build retries that do not amplify the outage

Treat 529 like “429 without Retry-After.” Use exponential backoff starting at about 2 seconds, add jitter, cap it at 30–60 seconds, and give up after about five attempts to queue the work. Jitter is the key. Without it, every client returns at the same moment and prolongs the overload you were trying to escape.

Pass it through instead of dropping it

Define a fallback chain for latency-sensitive paths. With an OpenAI-compatible endpoint, you change only one string — there is no need to create a new SDK or 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 particular request type returns 529 while other calls at the same time succeed, it is not a full outage. Check whether that path sends an unusually large prompt or makes consecutive calls in a tight loop. Conversely, if every call becomes 529 at once and then settles on its own, the cause is capacity. The things to fix then are retries and fallbacks, not refactoring.

Is 529 my fault?

No. It is a provider-side capacity issue. Your responsibilities are limited to two things — not amplifying the outage (backoff and jitter), and having a way around it when the outage lasts longer than your latency budget.

What is the difference between 529 and 429?

429 means you exceeded your limit while the server is healthy. 529 means the server itself is overloaded while your limit is healthy. Both are retryable, but only 429 comes with a Retry-After hint.

How long does a 529 condition usually last?

It cannot be predicted or guaranteed. That is why the answer is capped backoff and a queue, not embedding a fixed wait time in your code. If the path has a latency budget, fallback should take over instead of waiting.

Are calls that fail with 529 billed too?

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