Anthropic 529 in the retry policy: where overloaded_error sits among 429, 500, 504

TL;DR: A 529 means the API is temporarily overloaded. It belongs in the retryable 5xx bucket of your retry policy, distinct from 429s and from 500s that need a requestid. Never blind-retry. - 429 ratelimit_error: honor the retry-after header and resume at a sustainable pace. A 529 almost never needs support.

The fix

TL;DR: A 529 means the API is temporarily overloaded. It belongs in the retryable 5xx bucket of your retry policy, distinct from 429s and from 500s that need a requestid. Never blind-retry. - 429 ratelimit_error: honor the retry-after header and resume at a sustainable pace. A 529 almost never needs support.

529 overloaded_error: place it in the retry policy, not in the debugger

Overload is transient and external: high traffic across all users, or a sharp spike on your side. Your request was fine. What matters is that your retry policy treats each status class differently, because the wrong response to a 529 looks exactly like the right response to something else.

The status-class retry policy

• 4xx (400, 401, 403, 404, 409, 413): fix the request or the account. Never blind-retry.
• 429 ratelimiterror: honor the retry-after header and resume at a sustainable pace. Exception: a 429 with no retry-after and error code enforcedspendlimit_reached is the monthly spend cap, and no wait clears it.
• 529 overloadederror and 500 apierror: exponential backoff with jitter, honoring retry-after when present. The official SDKs already retry 5xx twice by default; the client accepts max_retries to tune or disable this.
• 504 timeout_error: retry once, then restructure to streaming instead of retrying harder.

What to do on a 529

1. Back off exponentially. Do not increase concurrency to push through; more pressure on an overloaded system fails more and can look like abuse.
2. Do not confuse a 529 with an acceleration 429. A sharp increase in your own usage can produce 429s from acceleration limits even when the API as a whole is healthy; the fix there is ramping gradually, not backing off from overload.
3. If 529s persist, check the Anthropic status page. A widespread incident means waiting, not code changes.
4. A 500 that persists across backoff is different from a 529: capture the request_id and contact support. A 529 almost never needs support.

The trap

One retry policy for everything. Blind retries on 4xx burn loops, immediate retries on 429 stay pinned at the ceiling, and rewriting your request in response to a 529 burns tokens fixing something that was never broken. The other trap: reading an acceleration 429 as overload and waiting, when the fix is smoothing your own ramp.

Checklist

• Your HTTP client should branch retries on status class before it branches on error type.
• 529: back off. Persistent 500: request_id to support. 429 without retry-after: check the spend cap, not the clock.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Anthropic 529 in the retry policy.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Anthropic behavior.

Anthropic's error reference: 529 overloadederror means the API is temporarily overloaded, often from high traffic; SDKs auto-retry 5xx with exponential backoff twice by default honoring retry-after, configurable via maxretries. Verified live at https://platform.claude.com/docs/en/api/errors.