Claude Code 529 Overloaded: Ursachen, Retry-Einstellungen und Lösungen

Wokey Team · 2026-09-24

Kurz gesagt: Ein 529 bedeutet, dass das Upstream-Modell gerade keine Kapazität mehr hat („overloaded“). Mit deinem Guthaben, deinem Kontingent oder deinem API-Key hat das nichts zu tun. Claude Code hat die Anfrage bereits mehrfach wiederholt, bevor es den Fehler anzeigt. Am schnellsten hilft ein Modellwechsel mit /model, denn die Kapazität wird pro Modell verwaltet. Wenn es nicht eilt, warte ein paar Minuten und sende erneut.

Der genaue Fehler

In Claude Code siehst du:

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Die Dokumentation von Claude Code hält dazu drei Punkte fest:

• Es ist ein vorübergehender Kapazitätsengpass, der alle Nutzer betrifft.
• Claude Code hat die Anfrage mehrfach wiederholt, bevor es den Fehler anzeigt.
• Ein 529 ist nicht dein Nutzungslimit und wird nicht auf dein Kontingent angerechnet.

Wenn du dich mit ANTHROPIC_BASE_URL über ein Gateway verbindest, nennt der letzte Satz den Host des Gateways statt status.claude.com.

Woher ein 529 bei Wokey kommt

Wokey erzeugt selbst nie einen 529; der Status kommt immer vom Upstream-Modell. Wokey geht in drei Schritten damit um:

1. Meldet der Upstream eine Überlastung (zum Beispiel Anthropics overloaded_error), wiederholt Wokey deine Anfrage zuerst über eine andere Upstream-Route für dasselbe Modell. Davon bekommst du nichts mit.

2. Nur wenn auch der neue Versuch überlastet ist, reicht Wokey den Upstream-Status durch. Der HTTP-Status bleibt 529. Der Body nutzt das Standard-Fehlerformat von Wokey, mit dem Wortlaut des Upstreams in message:

   {"error":{"code":"upstream_overloaded","message":"Overloaded","type":"invalid_request_error"}}
   

3. Tritt die Überlastung auf, nachdem das Streaming der Antwort begonnen hat, kommt sie als error-Event im Stream an und nicht als HTTP 529.

Ein 529 über Wokey bedeutet also, dass mehrere Upstream-Routen für dasselbe Modell gleichzeitig überlastet waren – meist während einer Lastspitze beim Anbieter. Diese Antworten enthalten keinen Retry-After-Header; dein Client wiederholt die Anfrage nach seinem eigenen Backoff-Schema.

Abgrenzung zu anderen Fehlern

Nur 529 und 503 bedeuten „der Upstream ist ausgelastet“. Bei den anderen musst du selbst etwas tun.

Was tun

1. Warten und erneut senden. Eine Überlastung legt sich meist innerhalb von Minuten, und die automatischen Wiederholungen von Claude Code fangen kurze Spitzen bereits ab.

2. Mit /model das Modell wechseln. Die Kapazität wird pro Modell verwaltet; ist Opus überlastet, funktioniert Sonnet oft noch. Führe /model in der Sitzung aus und wähle ein anderes Modell; ein Neustart ist nicht nötig.

3. Bei unbeaufsichtigten langen Jobs hartnäckiger wiederholen. Ergänze den env-Block von ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• Mit CLAUDE_CODE_RETRY_WATCHDOG=1 wiederholt Claude Code 429- und 529-Fehler unbegrenzt und wartet zwischen den Versuchen bis zu 5 Minuten. Das passt zu Jobs, die über Nacht laufen.
• Für nur ein paar zusätzliche Versuche setzt du stattdessen CLAUDE_CODE_MAX_RETRIES. Der Standard ist 10, das Maximum 15.

4. Im eigenen Code Spielraum für Wiederholungen bei 529 lassen. Die offiziellen Anthropic-SDKs wiederholen 5xx-Fehler, auch 529, standardmäßig zweimal. Erhöhe für Batch-Jobs max_retries und lege exponentielles Backoff um den Aufruf.

Ein 529 in Codex

Codex behandelt 5xx-Fehler, auch 529, als wiederholbar:

• Die HTTP-Schicht wiederholt standardmäßig 4-mal (request_max_retries des Providers).
• Die Stream-Schicht wiederholt danach bis zu 5 weitere Male (stream_max_retries).
• Scheitern alle Versuche, beginnt der Fehler mit unexpected status 529, gefolgt vom Body der Antwort.

Steht in diesem Body der code upstream_overloaded, handelt es sich um die oben beschriebene Überlastung des Upstreams. Die Lösung ist dieselbe: warten oder in config.toml das Modell wechseln. Die vollständige Einrichtung von Codex findest du in der Anleitung zur Codex config.toml.