Fehler der Claude API lassen sich grob in drei Gruppen teilen: Zugangsdaten und Anfrageformat, Ratenbegrenzung und Kapazität sowie Kontextlänge. Die Reihenfolge der Behandlung sollte sein: zuerst HTTP-Statuscode und Fehlertyp, dann die Request-ID, und erst zuletzt der Prompt. Ist die Reihenfolge umgekehrt, wird ein Konfigurationsproblem leicht als Modellproblem behandelt.

Dieser Artikel teilt die Fälle in 401, 429, 529 overloaded und Kontextüberschreitung und nennt Ursachen, Prüfschritte und wiederverwendbaren Backoff-Code. Modelle und Preise richten sich nach den Modellpreisen.

Hinweis: Anthropic und Claude sind Marken der jeweiligen Inhaber. Fehlertypen und Schnittstellenverhalten können sich mit Versionen ändern; der Artikel beschreibt den üblichen Stand Oktober 2026, maßgeblich ist die offizielle Dokumentation.

1. Zuerst den Statuscode ansehen, nicht den Prompt ändern

Statuscode Fehlertyp Bedeutung Wiederholen?
400 invalid_request_error Parameter, Format oder Kontextlänge fehlerhaft Anfrage ändern, dann erneut
401 authentication_error Key fehlt, ist falsch oder ungültig nicht wiederholen, Zugangsdaten korrigieren
403 permission_error Key ohne Modell- oder Projektrecht nicht wiederholen, Rechte prüfen
404 not_found_error Pfad oder Modellname falsch nicht wiederholen, Dokumentation prüfen
413 request_too_large Request-Body zu groß aufteilen und erneut
429 rate_limit_error Frequenz, Parallelität oder Token überschritten nach Backoff wiederholen
500 api_error interner Serverfehler nach Backoff wiederholen
529 overloaded_error Server überlastet nach Backoff wiederholen

Die request-id aus dem Antwortheader aufbewahren. Bei der Fehlersuche mit dem Anbieter ist eine Request-ID nützlicher als zehn Screenshots. Im Log mindestens Zeitpunkt, Statuscode, Fehlertyp, Modellname und Request-ID speichern, niemals den vollständigen Key oder sensible Inhalte.

2. 401: zuerst Header, dann Key prüfen

401 bedeutet, dass die Identität nicht bestätigt wurde; mit Guthaben oder Modellfähigkeit hat das nichts zu tun. Prüfung in dieser Reihenfolge:

  1. Wird x-api-key verwendet und nicht Authorization: Bearer? Die Claude Messages API authentifiziert nicht über Bearer.
  2. Ist anthropic-version: 2023-06-01 gesetzt? Ein fehlender Versionsheader erscheint manchmal als 400, aber die Ergänzung ist der einfachere Weg.
  3. Stehen vor oder hinter dem Key Leerzeichen, Zeilenumbrüche oder überzählige Anführungszeichen? Die Kopie aus einem Chatfenster ist die häufigste Ursache.
  4. Wurde die Umgebungsvariable wirklich geladen? Nur das Präfix prüfen und den vollständigen Key nicht ins Log schreiben.
  5. Wurde der Key gesperrt, oder gehört er nicht zur aktuellen Organisation bzw. zum Projekt?
  6. Zeigt die Base URL auf die richtige Umgebung, und lautet der Pfad /v1/messages?
export ANTHROPIC_API_KEY="sk-dein-schluessel"

curl "https://ai.zhongshangqihang.com/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "Antworte nur mit OK"}]
  }'

Status 200 zeigt, dass Key, Base URL und Modellname stimmen. Bleibt es bei 401, denselben Key an einem anderen Einstieg testen; so lässt sich unterscheiden, ob der Key selbst oder die Gateway-Konfiguration bzw. Netzschicht die Ursache ist. Maßgeblich für Modellnamen sind die Modellpreise.

3. 429: Ratenbegrenzung ist kein „fehlendes Guthaben“

429 bedeutet, dass die Anfrage eine Rate- oder Kontingentgrenze überschreitet. Häufige Auslöser:

  • Anfragen pro Minute oder Token pro Minute überschritten.
  • Parallelität steigt plötzlich und füllt das Kontingent kurzfristig aus.
  • Mehrere Dienste teilen einen Key und verdrängen sich gegenseitig.
  • Wiederholungen ohne Backoff erzeugen mit jedem Fehlschlag mehr Last und einen Retry-Sturm.
  • Lange Ausgaben belegen viele Ausgabe-Token und lassen weniger Raum für Parallelität.
Symptom Mögliche Ursache Behandlung
429 gehäuft zur Spitzenzeit Verkehrsspitze Warteschlange, gleichmäßiger senden
429 bei einem Key für mehrere Dienste geteiltes Kontingent Keys je Projekt trennen
nach Wiederholungen schlimmer Retry ohne Backoff exponentielles Backoff mit Jitter
lange Anfragen zuerst 429 hoher Ausgabe-Token-Anteil max_tokens oder Parallelität senken

Zuerst retry-after aus der Antwort prüfen, falls vorhanden, und daraus die Wartezeit ableiten. Das SDK unterscheidet RateLimitError und allgemeine APIStatusError; den Typ verwenden, nicht die Fehlermeldung als Zeichenkette vergleichen.

import random
import time
from anthropic import Anthropic, APIStatusError, RateLimitError

client = Anthropic()

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.messages.create(
                model="claude-sonnet-5-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": prompt}],
            )
            return resp.content[0].text
        except RateLimitError:
            wait = min(2 ** attempt, 20) + random.random()
            print(f"429, Versuch {attempt + 1}, warte {wait:.1f}s")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                print(f"{exc.status_code}, neuer Versuch in {wait:.1f}s")
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("Wiederholungsversuche ausgeschöpft")

Wiederholungen sind nur bei vorübergehenden Fehlern sinnvoll. Bei Vorgängen mit bereits eingetretenen Nebenwirkungen zuerst mit Idempotenzschlüssel oder Statusabfrage klären, ob die Ausführung stattgefunden hat, und erst dann erneut senden.

4. 529 overloaded: Serverüberlast, nicht das eigene Kontingent

529 mit overloaded_error bedeutet, dass der Server aktuell überlastet ist, meist unabhängig vom eigenen Volumen. Die Behandlung unterscheidet sich von 429: Bei 429 zuerst eigene Parallelität und Kontingent prüfen, bei 529 den Dienststatus und die Last senken.

  1. Sicherstellen, dass der Fehlertyp overloaded_error ist und nicht als ungültiger Key behandelt wird.
  2. request-id und Zeitpunkt für den Anbieter aufbewahren.
  3. Exponentielles Backoff mit Jitter und eine maximale Anzahl verwenden, nicht in festem Intervall wiederholen.
  4. Parallelität senken, Warteschlangen bilden und bei Bedarf nicht-kritische Aufgaben vorübergehend aussetzen.
  5. Ein Ausweichmodell oder einen Ausweichkanal vorbereiten, sofern das Geschäft Qualitätsänderungen zulässt.
  6. Bei unerwartet langer Dauer den Anbieter mit Request-ID kontaktieren.

Wiederholungen im Sekundentakt verwandeln eine kleine Störung in einen Lawinenausfall. Die Retry-Strategie braucht eine Obergrenze und Alarmierung, keine Endlosschleife.

5. Kontextüberschreitung: erst messen, dann aufteilen

Eine Kontextüberschreitung liefert meist 400 invalid_request_error; die Meldung enthält prompt is too long. Die Ursache ist kein defektes Modell, sondern ein Budget aus Eingabe plus Ausgabe, das das Kontextfenster übersteigt.

Häufige Quellen: ungekürzter Dialogverlauf, komplette Logausgaben aus Tool-Aufrufen, vollständige Dokumente, zu viele Bilder, ein sehr langer System-Prompt. Die Reihenfolge:

  1. Vor der Anfrage die Eingabe mit count_tokens quantifizieren, nicht nach Zeichenzahl schätzen.
  2. Die älteste Historie kürzen und nur System-Prompt, letzte Runden und eine Zusammenfassung behalten.
  3. Dokumente zuerst per Retrieval auf relevante Passagen reduzieren, nicht die gesamte Datenbank hineingeben.
  4. Lange Dokumente nach Kapiteln aufteilen, abschnittsweise verarbeiten und Ergebnisse zusammenführen.
  5. Tool-Ausgaben komprimieren und nur notwendige Felder zurückgeben, nicht die vollständige Antwort wiederholt mitschicken.
  6. Platz für die Ausgabe lassen. max_tokens begrenzt die Ausgabe, aber Eingabe und Ausgabe müssen gemeinsam in den Kontext passen.
import os
from anthropic import Anthropic

client = Anthropic()
MODEL = "claude-sonnet-5-5"
LIMIT = int(os.environ.get("CONTEXT_BUDGET", "200000"))  # eigenes Budget, nicht Modellgrenze

def fit_messages(messages):
    while client.messages.count_tokens(model=MODEL, messages=messages).input_tokens > LIMIT:
        if len(messages) <= 2:
            raise ValueError("Einzelne Nachricht überschreitet das Budget, Dokument aufteilen")
        messages = messages[2:]  # älteste user/assistant-Runde entfernen
    return messages

LIMIT ist ein selbst gesetztes Budget des Teams, keine Modellspezifikation. Ein etwas niedrigeres Budget als die Modellgrenze lässt Spielraum für Ausgabe und Tool-Aufrufe.

6. Eine Tabelle zur Prüfreihenfolge

  1. Statuscode, Fehlertyp, request-id, Modellname und Zeitpunkt erfassen.
  2. Bei 401 und 403 Zugangsdaten und Rechte prüfen; bei 404 Pfad und Modellnamen.
  3. Bei 400 Parameter, Kontextlänge, Bildformat und Größe des Request-Bodys prüfen.
  4. Bei 429 Kontingent, Parallelität, geteilte Keys und Retry-Stürme prüfen.
  5. Bei 529 Dienststatus prüfen, Backoff, Parallelität senken und Degradation vorbereiten.
  6. Bei 500 zuerst mit Backoff wiederholen; bei anhaltendem Fehler den Anbieter mit Request-ID kontaktieren.
  7. Nach jeder Störung Monitoring und Alarme ergänzen, statt auf Nutzerrückmeldungen zu warten.

Häufige Fragen

Worin unterscheiden sich 429 und 529?

429 bedeutet, dass die eigene Anfrage eine Rate- oder Kontingentgrenze überschreitet; zuerst eigene Parallelität, Keys und Nutzung prüfen. 529 bedeutet Serverüberlast; hier helfen Backoff, weniger Parallelität und ein Blick auf den Dienststatus. Beide erfordern Wiederholungen, aber die Prüfrichtung ist anders.

Warum schlägt es trotz Wiederholungen weiter fehl?

Möglicherweise fehlt Backoff, die Parallelität ist zu hoch, mehrere Dienste teilen einen Key, oder die Anfrage ist selbst ein 400. Wiederholungen lösen nur vorübergehende Fehler, keine Parameter- oder Rechteprobleme.

Ist prompt is too long ein Modellfehler?

Nein. Die Eingabe überschreitet das Kontextfenster. Zuerst mit count_tokens messen, dann Historie kürzen, Dokumente aufteilen oder Retrieval einsetzen; nicht einfach weitere Prompts anhängen.

Wie oft sollte wiederholt werden?

Eine einheitliche Zahl gibt es nicht; die Obergrenze richtet sich nach der Geschäftstoleranz, etwa 3–5 Versuche, danach Degradation oder Alarm. Das Intervall muss ansteigen und Jitter enthalten, damit nicht alle Clients gleichzeitig erneut senden.

Wie unterscheidet man Gateway- und offizielle Fehler?

Zuerst Fehlertyp und request-id ansehen, dann dieselbe Anfrage an den offiziellen und den Gateway-Einstieg senden. So lässt sich schnell erkennen, ob Key, Netz, Gateway-Konfiguration oder Upstream die Ursache ist.

Nächster Schritt

Im ZSQH AI Gateway einen Test-Key anlegen und 401, 429, 529 sowie die Kontextüberschreitung jeweils einmal durchspielen, bevor die Produktionsüberwachung angebunden wird. Verfügbarkeit und Preise entnehmen Sie den Modellpreisen.

Weiterlesen: