Claude API returns 529 overloaded_error ('Overloaded') or 500 api_error: is it my code, and how should I retry?

Cause: a 529 with error type overloaded_error means the Claude API is temporarily overloaded across all users. It is not caused by your request and not by your rate limits. A 500 api_error is an unexpected internal error. Both are transient. Don't confuse them with 429 rate_limit_error (your organization hit a rate limit or spend cap) or 400 invalid_request_error (something wrong with the request), which need different fixes. How to check: - Read the JSON body: error.type is overloaded_error (529) or api_error (500). Note the request_id field (also in the request-id response header) for support. - Check the Anthropic status page to see whether an incident is open. - In streaming responses, an overloaded error can arrive as an error event after the request already returned 200, so handle error events in the stream as well as HTTP status codes. Fix: 1. Retry with exponential backoff and jitter. The official SDKs already retry connection errors, 429s and 5xx errors twice by default with exponential backoff, honoring retry-after when present; raise max_retries (maxRetries in TypeScript) if you need more, instead of wrapping your own tight retry loop around the SDK. 2. Catch the SDK's typed exceptions (for example anthropic.InternalServerError / APIStatusError with status 529 in Python) rather than matching error message strings. 3. For long or large jobs, use streaming or the Message Batches API, which handle long-running work better than one long blocking request. 4. For production resilience, consider a fallback model or provider route for user-facing requests while errors persist. After: if 529s persist for a long time with no status-page incident, contact support with the request IDs. If you are instead seeing 429s after a sudden traffic spike, ramp traffic up gradually, since the API applies acceleration limits to sharp increases. Sources: https://platform.claude.com/docs/en/api/errors https://platform.claude.com/docs/en/build-with-claude/streaming#error-events https://status.anthropic.com