Claude-Fehler 529 overloaded_error — Ursache und Retry-Strategie

529 ist der einzige Claude-Fehler, den dein Code nicht verursacht hat: Anthropic ist überlastet. Du kannst ihn nicht beheben, sondern nur sauber abfangen. Das bedeutet geduldige Wiederholungen mit Backoff, ein Ersatzmodell für latenzkritische Pfade und vor allem keine sofortigen Retry-Stürme, die den Vorfall verschärfen.

Der Fehler

réponse (HTTP 529)

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

Ursachen und Lösungen im Überblick

Ursache	Lösung
Überlastung auf Anbieterseite (Launch-Tage, regionale Vorfälle). Betrifft alle Kunden gleichzeitig.	Backoff mit Jitter; prüfe die Statusseite von Anthropic, statt deine Anwendung neu bereitzustellen.
Dein eigener Lastspitzenzeitraum trifft auf bereits angespannte Kapazität.	Verteile Batch-Verarbeitungen zeitlich; eine Verzögerung von zehn Minuten reicht normalerweise aus.
Verwechslung mit 429: In Logs sieht eine Ratenbegrenzung ähnlich aus, aber die Ursache ist eine andere.	429 bedeutet, dass du deine Limits überschritten hast (der Server ist in Ordnung); 529 bedeutet, dass der Server überlastet ist (dein Kontingent ist in Ordnung). Nur 429 wird von einem Retry-After-Hinweis begleitet.
Kein Fallback definiert, sodass ein Anbieterproblem bis zum Endnutzer durchgereicht wird.	Definiere eine Fallback-Kette — innerhalb derselben Familie (Sonnet → Haiku) bleibt das Verhalten ähnlich; zwischen Anbietern (Claude → GPT) überstehst du einen vollständigen Ausfall.

Wiederholen, ohne den Vorfall zu verschärfen

Behandle 529 wie 429 ohne Retry-After: exponentieller Backoff ab etwa 2 Sekunden, mit Jitter, begrenzt auf 30–60 Sekunden, Abbruch nach ungefähr fünf Versuchen und Einreihung der Arbeit in eine Warteschlange. Der Jitter ist entscheidend: Ohne ihn kommen alle Clients gleichzeitig zurück und verlängern genau die Überlastung, der sie entkommen wollen.

Umschalten statt ausfallen

Definiere für latenzkritische Pfade eine Fallback-Kette. An einem OpenAI-kompatiblen Einstiegspunkt muss nur eine Zeichenfolge geändert werden — kein zweites SDK, kein zweites Konto:

failover.py

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          # saturé — passer au palier suivant
    raise last

Erst danach den eigenen Code prüfen

Wenn 529 nur bei einer Anfrageart auftreten, während andere Aufrufe zur gleichen Zeit funktionieren, handelt es sich nicht um einen allgemeinen Vorfall: Prüfe, ob dieser Pfad ungewöhnlich große Prompts sendet oder in einer engen Schleife läuft. Wenn dagegen alle Aufrufe gleichzeitig betroffen sind und der Fehler von selbst verschwindet, lag es an der Kapazität — dann sind Retry und Fallback zuständig, nicht ein Refactoring.

Wenn Sie Kunavo verwenden

Kunavo leitet Claude über mehr als einen Upstream-Pfad weiter, und sein Multi-Modell-Katalog macht den Anbieterwechsel zu einer einfachen Änderung des Modellnamens mit demselben Schlüssel und demselben Wallet — das obige Muster benötigt kein zweites Konto. 529-Fehler, die dich trotzdem erreichen, werden niemals berechnet. Kapazität und Preis sind zwei verschiedene Fragen; für Letzteres finden Sie die modellbezogenen Tarife in der Claude-API-Preistabelle.

Häufig gestellte Fragen

Ist ein 529-Fehler meine Schuld?

Nein. Es handelt sich um ein Kapazitätsproblem auf Anbieterseite. Ihre einzige Verantwortung besteht darin, den Vorfall nicht zu verschärfen (Backoff, Jitter) und eine Ausweichlösung bereitzuhalten, falls der Vorfall länger dauert als Ihr Latenzbudget.

529 oder 429 – worin besteht der Unterschied?

429 bedeutet, dass Sie Ihre Limits überschritten haben; der Server funktioniert ordnungsgemäß. 529 bedeutet, dass der Server selbst überlastet ist; Ihr Kontingent ist in Ordnung. Beide Fehler können erneut versucht werden; nur 429 liefert einen Retry-After-Hinweis.

Wie lange dauert ein 529-Zeitraum?

Das ist nicht vorhersehbar und kann nicht garantiert werden – deshalb besteht die richtige Lösung aus einem begrenzten Backoff plus einer Warteschlange und nicht aus einer fest im Code hinterlegten Verzögerung. Wenn Ihr Pfad ein Latenzbudget hat, übernimmt die Ausweichlösung, statt zu warten.

Werden 529-Anfragen berechnet?

Über Kunavo: nein. Eine Anfrage, die mit einem Fehler endet, wird nicht berechnet. Bei einem direkten Vertrag hängt dies von den Abrechnungsregeln des jeweiligen Anbieters ab.

Claude-API-Fehler 529 overloaded_error — was er bedeutet und wie du ihn abfängst