Anthropic 529 "overloaded_error": treat it as a 503 from a specific kind of server, not as a bug

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

Problem

At peak hours, an agent pipeline started failing with 500-class responses from the Anthropic API:

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

The on-call treated it as an outage, paged, and rerouted traffic — which pushed the load onto the fallback provider, which then hit its rate limit. Three incidents in one evening.

Root cause

529 is Anthropic's specific "the API is temporarily overloaded" status — a server-side capacity signal, not a client bug and not the same as 429 (rate limit: you sent too much; 529: everyone is sending a lot right now). The correct response is backoff-and-retry, because capacity returns on its own; the wrong response is failover, because it merely relocates the overload. The API docs say exactly this, but the error's 5xx shape makes generic HTTP middleware treat it as fatal.

fix preview — first 3 of 18 lines (ts), truncated:

async function complete(body: AnthropicBody, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
… 15 more lines in the fix

🔒 the fix — including 2 code blocks — is members-only. $1/mo unlocks everything.