Claude API-Fehler erklärt: Serverfehler 500, Überlastung 529, Ratenlimit 429, fehlerhafte Anfrage 400 — und die jeweilige Lösung

Jeder Entwickler, der die Claude API nutzt, stößt irgendwann auf Fehler. Einige liegen bei Ihnen (fehlerhaft formatierte Anfragen), andere bei Anthropic (Serverprobleme), und manche sind architekturbedingt (Ratenlimits bei intensiver Nutzung). Dieser Leitfaden behandelt alle gängigen Fehlercodes der Claude API mit tatsächlichen Ursachen, konkreten Lösungen und einer für den Produktivbetrieb geeigneten Wiederholungslogik. Außerdem erklärt er, wie das Routing über ein Gateway mit mehreren vorgelagerten Konten die Häufigkeit von Ratenlimit- und Überlastungsfehlern verringern kann.

Zugriff und Modell vor einem erneuten Versuch prüfen

Vergewissern Sie sich, dass Ihr Zugang über einen Tarif oder ein Guthaben aktiv ist, prüfen Sie die Schlüsselgruppe und verwenden Sie ein Modell, das für diesen Schlüssel zurückgegeben wird. Eine erfolgreiche Antwort auf die Modelllistenabfrage ist eine erste Prüfung; testen Sie eine kleine Generierungsanfrage, bevor Sie einen größeren Agentenlauf starten.

Verwenden Sie Modelle und Schlüsselgruppen und die Checkliste zur Agenteneinrichtung um Zugriffsprobleme von Problemen mit der Tool-Konfiguration und Fehlern vorgelagerter Anbieter zu unterscheiden.

„Claude-Serverfehler“: Welcher liegt tatsächlich vor?

„Claude-Serverfehler“ geben Nutzer ein, wenn die API nicht mehr antwortet. Die Zahl in der Meldung bestimmt jedoch, was zu tun ist. Ein **500** bedeutet einen internen Fehler der API — warten Sie, versuchen Sie es erneut oder wechseln Sie das Modell. Ein **529** bedeutet, dass das Modell für alle ausgelastet ist — gehen Sie genauso vor; der Zustand löst sich von selbst auf. Ein **429** bedeutet, dass Sie ein Limit erreicht haben — verlangsamen Sie die Anfragen oder reduzieren Sie parallele Anfragen.

Ein **400** bedeutet, dass die Anfrage selbst abgelehnt wurde — dieselbe Anfrage erneut zu senden, wird wieder fehlschlagen. Suchen Sie unten nach Ihrem Fehlercode; jeder Abschnitt nennt die genaue Meldung, die Ursache und die Lösung. Wenn der Fehler in Claude Code statt in Ihrem eigenen Code auftritt, behandeln die Claude-Code-Fehlerleitfäden unter /claude-code/errors/ die CLI-spezifischen Meldungen (OAuth-Zeitüberschreitungen, „Prozess mit Code 1 beendet“, gleichzeitige Tool-Nutzung).

Fehler 400 — Ungültige Anfrage

Ein Fehler 400 bedeutet, dass Ihre Anfrage strukturell ungültig ist. Die Claude API hat sie abgelehnt, bevor sie überhaupt versucht hat, eine Antwort zu generieren. Der Antwortkörper des Fehlers enthält eine Meldung, die erklärt, was falsch ist — lesen Sie sie immer sorgfältig. Häufige Ursachen sind: Das messages-Array ist leer oder fehlerhaft aufgebaut, das content-Feld ist null statt einer Zeichenfolge, max_tokens überschreitet das Limit des Modells, die Modellkennung existiert nicht, der System-Prompt hat das falsche Format oder die Tool-Definitionen enthalten Schemafehler.

Der häufigste Fehler 400 für Nutzer von Claude Code ist eine überschrittene Kontextlänge. Wenn Ihr Gesprächsverlauf über das Kontextfenster des Modells hinauswächst (200K Tokens bei den meisten Claude-Modellen), gibt die API einen 400 mit einer Meldung zurück, dass die Eingabe zu lang ist. Die Lösung besteht darin, den Verlauf mit /compact zusammenzufassen, große Dateiinhalte aus dem Kontext zu entfernen oder eine neue Sitzung zu starten. Dies ist kein Ratenlimit — es ist eine feste Beschränkung der Anfragegröße.

Ein weiterer häufiger 400 entsteht beim Senden eines nicht unterstützten Parameters oder einer nicht unterstützten Modellversion. Wenn Sie kürzlich Ihr SDK aktualisiert oder Modellkennungen geändert haben, prüfen Sie sorgfältig, ob jedes Feld Ihrer Anfrage der aktuellen API-Spezifikation entspricht. Bei Modell-IDs wird zwischen Groß- und Kleinschreibung unterschieden, und sie sind versionsspezifisch — 'claude-opus-4-6' ist gültig, 'Claude-Opus-4.6' hingegen nicht. Fragen Sie im Zweifelsfall den Endpunkt /v1/models ab, um genau zu sehen, welche Kennungen der Anbieter akzeptiert.

Fehler 400 – „Eingabe ist für das angeforderte Modell zu lang“

Dieser konkrete Fehler 400 bedeutet, dass Ihre Anfrage (System-Prompt + Nachrichten + etwaige Tool-Definitionen) das Kontextfenster des Modells überschreitet. Es handelt sich nicht um ein Ratenlimit, und ein erneuter Versuch behebt das Problem nicht — dieselbe Nutzlast schlägt jedes Mal fehl, bis Sie die Eingabe verkleinern oder zu einem Modell mit größerem Kontextfenster wechseln.

Drei praktische Lösungen, nach Aufwand geordnet: Kürzen Sie zunächst den Gesprächsverlauf, den Sie erneut senden — die meisten Chat-Apps benötigen nur die letzten Gesprächsrunden und eine fortlaufende Zusammenfassung, nicht das vollständige Protokoll. Zählen Sie zweitens die Tokens vor dem Senden (der Endpunkt zur Token-Zählung ist kostenlos) und setzen Sie in Ihrem Code ein festes Eingabebudget durch. Wenn Sie drittens tatsächlich den vollständigen Kontext benötigen — ganze Repositorys oder Dokumente in Buchlänge — wechseln Sie zu einem Modell mit einem Kontextfenster von 1M, etwa Fable 5, in das dieselbe Anfrage problemlos passt.

Eine häufige Stolperfalle bei agentengestützten Tools: Lang laufende Sitzungen sammeln Tool-Ergebnisse und Dateiinhalte an, bis eine weitere Gesprächsrunde die Anfrage über das Limit bringt. Wenn der Fehler mitten in einer Sitzung in Claude Code oder einem ähnlichen Agenten auftritt, komprimieren oder leeren Sie den Sitzungskontext, statt Ihren Prompt zu verkürzen.

Fehler 429 — „Ratenlimit erreicht“ / „Rate überschritten“

Derselbe Zustand erscheint unter zwei Formulierungen. Die API gibt HTTP 429 zurück, mit rate_limit_error; claude.ai und Claude Code zeigen dies als „Rate überschritten“ oder „Ratenlimit erreicht“ an. Unabhängig vom angezeigten Text ist die Ursache identisch: Ihr Konto hat sein Kontingent für das aktuelle Zeitfenster aufgebraucht, und Anfragen werden abgelehnt, bis es zurückgesetzt wird.

Ein 429 bedeutet, dass Sie die zulässige Anfragerate überschritten haben. Die Antwort enthält einen Retry-After-Header, der angibt, wie viele Sekunden Sie vor einem erneuten Versuch warten müssen. Die Ratenlimits von Anthropic gelten für mehrere Dimensionen: Anfragen pro Minute (RPM), Tokens pro Minute (TPM) und Tokens pro Tag (TPD). Sobald eines dieser Limits erreicht wird, wird ein 429 ausgelöst. Die Fehlermeldung gibt in der Regel an, welches Limit erreicht wurde.

Für Nutzer von Claude Code sind Ratenlimits der frustrierendste Fehler, weil sie den Workflow unterbrechen. Ein einzelner Entwickler, der Claude Code mit Unteragenten nutzt, kann bei parallelen Vorgängen leicht die RPM-Limits erreichen oder bei Sitzungen mit großen Dateien im Kontext die TPM-Limits. Die Limits unterscheiden sich je nach Kontostufe — niedrigere Stufen haben strengere Limits, die bei intensiver agentengestützter Nutzung regelmäßig überschritten werden.

Die richtige Reaktion auf einen 429 ist exponentielles Backoff mit Jitter. Warten Sie die in Retry-After angegebene Dauer ab und fügen Sie dann eine zufällige Verzögerung hinzu, um einen gleichzeitigen Ansturm zu vermeiden, wenn mehrere Clients gleichzeitig das Limit erreichen. Ein Gateway wie AI Prime Tech Unlimited hilft, 429-Fehler zu reduzieren, indem es Anfragen über mehrere Upstream-Konten verteilt und damit das verfügbare Kontingent effektiv vervielfacht. Wenn ein Upstream-Konto sein Ratenlimit erreicht, leitet das Gateway die Anfrage an ein anderes weiter.

Fehler 500 — Interner Serverfehler

Ein 500-Fehler bedeutet, dass auf der Serverseite etwas schiefgegangen ist — Sie sind nicht dafür verantwortlich und können das Problem nicht durch eine Änderung Ihrer Anfrage beheben. Diese Fehler sind vorübergehend: Dieselbe Anfrage, die mit einem 500 fehlgeschlagen ist, wird wahrscheinlich erfolgreich sein, wenn Sie sie nach einer kurzen Verzögerung erneut senden. Die Infrastruktur von Anthropic gibt bei Bereitstellungen, Kapazitätsänderungen oder internen Dienststörungen gelegentlich 500-Fehler zurück.

Die richtige Behandlung von 500-Fehlern besteht darin, die Anfrage mit Backoff erneut zu senden. Warten Sie 1-2 Sekunden und wiederholen Sie exakt dieselbe Anfrage. Schlägt sie erneut fehl, warten Sie 4 Sekunden, dann 8, bis zu einem Maximum von etwa 60 Sekunden. Die meisten 500-Fehler sind beim ersten Wiederholungsversuch behoben. Wenn Sie über mehrere Minuten hinweg durchgehend 500-Fehler erhalten, prüfen Sie die Statusseite von Anthropic oder den Statusendpunkt des Gateways auf bekannte Vorfälle.

Ändern Sie Ihre Anfrage nicht als Reaktion auf einen 500 — das Problem liegt auf der Serverseite. Eine Änderung Ihres Prompts, eine Reduzierung des Kontexts oder ein Modellwechsel helfen nicht und verschwenden Entwicklungszeit mit der Fehlersuche bei einem Problem, das nicht bei Ihnen liegt. Die einzigen Maßnahmen sind: erneut versuchen, länger warten, wenn Wiederholungsversuche fehlschlagen, und einen Alarm auslösen, wenn das Problem über einen angemessenen Zeitraum hinaus anhält (5-10 Minuten mit durchgehenden Fehlern).

Fehler 529 — „Der Claude-Server ist überlastet“ (overloaded_error)

Der Statuscode 529 ist Anthropic-spezifisch und bedeutet, dass die API stark nachgefragt wird — das angeforderte Modell ist vorübergehend ausgelastet. Anders als ein 429 (der bedeutet, dass das Ratenlimit für YOUR überschritten wurde) bedeutet ein 529, dass SYSTEM unabhängig von Ihren individuellen Limits überlastet ist. Sie haben nichts falsch gemacht; zu diesem Zeitpunkt übersteigt die Nachfrage schlicht die verfügbare Rechenkapazität.

529-Fehler treten am häufigsten zu Spitzenzeiten (während der US-Geschäftszeiten), unmittelbar nach der Veröffentlichung neuer Modelle (wenn alle das neue Modell gleichzeitig testen) und bei viralen Ereignissen auf, wenn die Nutzung über alle Kunden hinweg sprunghaft steigt. Bei Sonnet und Haiku sind sie seltener als bei Opus, da Opus pro Anfrage mehr Rechenleistung benötigt und strengeren Kapazitätsgrenzen unterliegt.

Behandeln Sie 529-Fehler mit längeren Backoff-Zeiten als 500-Fehler. Beginnen Sie mit einer Wartezeit von 5-10 Sekunden und erhöhen Sie diese exponentiell. Wenn Sie Produktionssysteme entwickeln, sollten Sie einen Modell-Fallback in Betracht ziehen: Wenn Opus 529 zurückgibt, weichen Sie für diese Anfrage auf Sonnet aus. Auch ein Gateway mit mehreren Upstream-Konten kann helfen — die Überlastung kann sich je nach Prioritätsstufe der Konten unterschiedlich auswirken und dem Gateway bei hoher Nachfrage mehr Routing-Optionen bieten.

„Kein funktionsfähiges Upstream-Backend“ — kein Claude-Fehler, sondern ein Infrastrukturfehler

„No healthy upstream“ wird nicht von der Claude API selbst zurückgegeben. Diese Meldung gibt ein Load Balancer oder Ingress-Proxy (üblicherweise Envoy) aus, wenn sämtliche dahinterliegenden Backend-Instanzen nicht verfügbar sind. Sie sehen sie während eines Ausfalls auf claude.ai sowie bei jedem Proxy oder Gateway, dessen Pool an Upstream-Verbindungen erschöpft ist oder Integritätsprüfungen nicht besteht.

In Ihrem Code gibt es nichts zu beheben. Behandeln Sie das Problem als vorübergehend: Prüfen Sie status.anthropic.com, warten Sie und versuchen Sie es mit exponentiellem Backoff erneut, genau wie bei einem 529. Wenn es am offiziellen Endpunkt länger als ein paar Minuten anhält, handelt es sich um einen Ausfall; stammt die Meldung von einem Drittanbieter-Gateway, hat dieses Gateway seine gesamte Upstream-Kapazität verloren.

Dies ist eines der Fehlerszenarien, die ein Gateway mit mehreren Konten abfangen soll: Wenn ein Upstream-Konto gedrosselt wird oder nicht funktionsfähig ist, wird die Anfrage an ein anderes weitergeleitet, statt den Fehler an Sie zurückzugeben.

Wiederholungslogik für den Produktionseinsatz

Eine gute Wiederholungslogik behandelt alle vorübergehenden Fehler (429, 500, 529) einheitlich mit exponentiellem Backoff und Jitter, während dauerhafte Fehler (400, 401, 403) nicht erneut versucht werden. Das Muster lautet: Anfrage senden, Statuscode prüfen, bei einem wiederholbaren Fehler mit Backoff warten und bis zu N-mal erneut versuchen, andernfalls sofort eine Ausnahme auslösen. Die maximale Anzahl der Wiederholungsversuche sollte bei den meisten Anwendungen 3-5 betragen.

Jitter verhindert synchronisierte Wiederholungsversuche. Wenn zehn Clients gleichzeitig ein Ratenlimit erreichen und alle nach exakt 2 Sekunden erneut anfragen, schlagen alle Anfragen wieder gleichzeitig fehl. Zufälliger Jitter (Multiplikation der Verzögerung mit einem Zufallsfaktor zwischen 0.5 und 1.5) verteilt die Wiederholungsversuche über die Zeit und verbessert die Erfolgsquote erheblich. Jeder Claude-API-Client im Produktionseinsatz sollte Jitter verwenden.

Implementieren Sie für Claude Code und agentische Workflows die Wiederholungslogik auf der Ebene des HTTP-Clients, damit einzelne Tool-Aufrufe und Subagent-Anfragen automatisch davon profitieren. Das Anthropic SDK enthält bereits eine grundlegende Wiederholungslogik, aber Sie können Zeitüberschreitungen und die maximale Anzahl der Wiederholungsversuche an Ihren Anwendungsfall anpassen. Wenn Sie AI Prime Tech Unlimited verwenden, übernimmt das Gateway Upstream-Wiederholungsversuche und Routing intern und reduziert so bereits die Fehler, die Ihr Client überhaupt erhält.

Wie ein Gateway diese Fehler reduziert

Ein gut konzipiertes Gateway wie AI Prime Tech Unlimited reduziert die Fehlerhäufigkeit auf mehrere Arten. Bei Ratenlimits (429) verteilt das Gateway Anfragen über mehrere Upstream-API-Konten, sodass Ihr effektives Ratenlimit der Summe aller Upstream-Konten entspricht und nicht dem Kontingent eines einzelnen Kontos. Bei Überlastungsfehlern (529) kann das Gateway die Anfrage über andere Upstream-Konten wiederholen, die möglicherweise andere Prioritätsstufen oder Positionen in der Warteschlange haben.

Bei Serverfehlern (500) kann das Gateway die Anfrage transparent wiederholen, bevor es den Fehler an Ihren Client zurückgibt — Sie erhalten eine etwas langsamere Antwort statt eines Fehlers. Bei 400-Fehlern kann das Gateway nicht helfen, da die Anfrage selbst ungültig ist. Gute Gateways liefern jedoch klarere Fehlermeldungen, mit denen Sie schneller debuggen können als mit unverarbeiteten Fehlerantworten von Anthropic.

Für Entwickler bedeutet dies insgesamt, dass weniger Fehler ihre Anwendung erreichen, weniger Wiederholungslogik auf der Clientseite benötigt wird und die Leistung zu Spitzenzeiten stabiler ist. Das ist besonders wertvoll für Claude-Code-Sitzungen, bei denen ein Fehler mitten in einer Aufgabe den Arbeitsfluss unterbrechen kann, und für Produktionsanwendungen, bei denen sich die Fehlerquote direkt auf die Nutzererfahrung auswirkt. Dank des Pauschalpreises des Unlimited-Tarifs entstehen Ihnen für diese Wiederholungsversuche und Umleitungen keine zusätzlichen Kosten.

import anthropic
import time
import random

client = anthropic.Anthropic(
    api_key="YOUR_KEY",
    base_url="https://aiprimetech.io",
)

def call_with_retry(messages, model="claude-sonnet-4-5", max_retries=4):
    for attempt in range(max_retries + 1):
        try:
            return client.messages.create(
                model=model,
                max_tokens=4096,
                messages=messages,
            )
        except anthropic.RateLimitError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            print(f"Rate limited, waiting {wait:.1f}s...")
            time.sleep(wait)
        except anthropic.InternalServerError as e:
            if attempt == max_retries:
                raise
            wait = (2 ** attempt) * random.uniform(0.5, 1.5)
            time.sleep(wait)
        except anthropic.BadRequestError:
            raise  # Don't retry 400s

# Usage:
resp = call_with_retry([{"role": "user", "content": "Hello"}])

Häufig gestellte Fragen

AI Prime Tech ist ein unabhängiges API-Gateway. Es ist weder mit Anthropic verbunden noch von Anthropic empfohlen und auch kein Wiederverkäufer von Anthropic. Claude und zugehörige Modellnamen sind Marken ihrer jeweiligen Inhaber.