Claude 529 overloaded_error — Ursache und richtige Retry-Strategie

529 ist der eine Claude-Fehler, den Ihr Code nicht verursacht hat: Anthropic selbst ist überlastet. Beheben können Sie ihn nicht — nur sauber abfangen. Das heißt: geduldige Wiederholungsversuche mit Backoff, ein Fallback-Modell für latenzkritische Pfade, und auf keinen Fall sofortige Retry-Stürme, die die Störung noch verstärken.

Die Fehlermeldung

Antwort (HTTP 529)

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

Ursachen und Abhilfe auf einen Blick

Ursache	Abhilfe
Auslastung auf Anbieterseite (Launch-Tage, regionale Störungen). Trifft alle Kunden gleichzeitig.	Backoff mit Jitter; die Statusseite von Anthropic prüfen, statt die eigene Anwendung neu zu deployen.
Ihr eigener Lastspitze trifft auf eine bereits angespannte Kapazität.	Batch-Jobs entzerren; zehn Minuten Verzögerung räumen das in der Regel ab.
Verwechslung mit 429: ein Rate-Limit sieht in Logs ähnlich aus, hat aber eine völlig andere Ursache.	429 heißt, Sie haben Ihre Limits überschritten (Server ist gesund); 529 heißt, der Server ist überlastet (Ihr Kontingent ist in Ordnung). Nur 429 liefert einen Retry-After-Hinweis mit.
Kein Fallback definiert, deshalb schlägt ein Anbieterproblem bis zum Endnutzer durch.	Eine Fallback-Kette festlegen — innerhalb der Familie (Sonnet → Haiku) bleibt das Verhalten ähnlich, anbieterübergreifend (Claude → Gemini) übersteht man auch einen kompletten Ausfall.

Wiederholen, ohne die Störung zu verstärken

Behandeln Sie 529 wie ein 429 ohne Retry-After: exponentielles Backoff ab etwa 2 Sekunden, mit Jitter, gedeckelt bei 30–60 Sekunden, nach rund fünf Versuchen aufgeben und die Arbeit in eine Queue legen. Entscheidend ist der Jitter: ohne ihn kommen alle Clients gleichzeitig wieder und verlängern genau die Überlastung, aus der sie herauswollen.

Ausweichen statt ausfallen

Für latenzkritische Pfade definieren Sie eine Fallback-Kette. Auf einem OpenAI-kompatiblen Endpunkt ist das eine einzige geänderte Zeichenkette — kein zweites SDK, kein zweites Konto:

failover.py

PREFERRED = ["claude-sonnet-4-6", "claude-haiku-4-5", "gemini-2-5-flash"]

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          # überlastet — nächste Stufe versuchen
    raise last

Erst dann in den eigenen Code schauen

Wenn 529 nur bei einem einzigen Request-Typ auftritt und andere Aufrufe zur selben Zeit durchgehen, ist es keine anbieterweite Störung: Prüfen Sie, ob dieser Pfad ungewöhnlich große Prompts schickt oder in einer engen Schleife feuert. Tritt es dagegen über alle Aufrufe hinweg gleichzeitig auf und verschwindet von selbst wieder, war es Kapazität — dann gehört die Arbeit in Retry und Fallback, nicht in ein Refactoring.

Wenn Sie über Kunavo aufrufen

Kunavo führt Claude über mehr als einen Upstream-Pfad, und der Multi-Modell-Katalog macht anbieterübergreifendes Failover zu einem geänderten Modellnamen auf demselben Schlüssel und derselben Abrechnung — das Muster oben braucht kein zweites Konto. 529er, die trotzdem bei Ihnen ankommen, werden nie abgerechnet. Kapazität und Preis sind zwei getrennte Fragen; für die zweite stehen die Sätze je Modell in der Claude-API-Preisliste.

Häufige Fragen

Ist ein 529 mein Fehler?

Nein. Es ist Kapazität auf Anbieterseite. Ihre Verantwortung beschränkt sich darauf, die Störung nicht zu verstärken (Backoff, Jitter) und ein Ausweichziel zu haben, falls der Vorfall länger dauert als Ihr Latenzbudget.

529 oder 429 — wo ist der Unterschied?

429 heißt, Sie haben Ihre Limits überschritten, der Server ist gesund. 529 heißt, der Server selbst ist überlastet, Ihr Kontingent ist in Ordnung. Beide sind wiederholbar; nur 429 bringt einen Retry-After-Hinweis mit.

Wie lange dauert eine 529-Phase üblicherweise?

Das ist nicht vorhersagbar und nichts, was man garantieren kann — deshalb ist die richtige Antwort ein gedeckeltes Backoff plus eine Queue, nicht eine Wartezeit, die man in den Code schreibt. Wenn Ihr Pfad ein Latenzbudget hat, greift statt des Wartens der Fallback.

Werden fehlgeschlagene 529-Aufrufe berechnet?

Über Kunavo nicht: eine Anfrage, die mit einem Fehler endet, wird nicht abgerechnet. Bei einem Direktvertrag hängt das von den Abrechnungsregeln des jeweiligen Anbieters ab.

Claude API 529 overloaded_error — was der Fehler heißt und wie Sie ihn aussitzen