Wenn Claude Code an eine Drittanbieter-API angebunden wird, sind die meisten Fehler keine Modellprobleme, sondern Konfigurations-, Authentifizierungs- oder Netzwerkprobleme: direkt nach dem Einrichten 401, nach einem Base-URL-Wechsel 404, mitten in der Aufgabe 429, lange Aufgaben hängen bis zum Timeout. Die Reihenfolge lautet: zuerst Statuscode und Fehlertyp, dann request-id, erst zuletzt der Prompt. Dieser Artikel trennt 401, 404, 429, Kontextüberschreitung und Timeout auf und liefert Diagnoseschritte, eine Log-Checkliste und Beispielcode. Modelle und Abrechnung entnehmen Sie den Modellpreisen.
Hinweis: Claude, Claude Code und Anthropic sind Marken ihrer jeweiligen Inhaber. Fehlertypen und Schnittstellenverhalten können sich mit Versionen ändern; dieser Artikel beschreibt gängige Fälle vom Oktober 2026, maßgeblich ist die offizielle Dokumentation.
1. Zuerst schichten: Auf welcher Ebene tritt der Fehler auf?
Eine Anfrage durchläuft vier Ebenen: Client, Netzwerk, Gateway und Upstream-Modell. Derselbe 401 kann ein falscher Key sein oder ein nicht passender Auth-Header; derselbe 404 kann ein zusätzliches /v1 im Pfad oder ein nicht existierender Modellname sein. Schichten Sie zuerst, damit Sie nicht in die falsche Richtung konfigurieren.
| Statuscode | Fehlertyp | Häufige Ursache | Behandlung |
|---|---|---|---|
| 400 | invalid_request_error | Parameter, Format, Kontextlänge oder Ausgabenlimit | Anfrage oder Limit ändern, dann erneut |
| 401 | authentication_error | Key fehlt, falsch, abgelaufen oder Header passt nicht | Zugangsdaten korrigieren, kein Retry |
| 402 | billing_error | Problem mit Abrechnung oder Zahlungsdaten | Abrechnung prüfen |
| 403 | permission_error | Key ohne Modell- oder Projektrecht | Berechtigungen prüfen |
| 404 | not_found_error | Falscher Pfad oder Modellname | Base URL und Modellname prüfen |
| 413 | request_too_large | Request-Body überschreitet Limit | Anfrage aufteilen |
| 429 | rate_limit_error | Rate, Parallelität oder Ausgabenlimit | Nach Backoff erneut |
| 500 | api_error | Interner Serverfehler | Mit Backoff erneut |
| 504 | timeout_error | Verarbeitung überschritt Zeitlimit | Streaming oder Stapelung |
| 529 | overloaded_error | Server überlastet | Backoff, Parallelität senken |
Die request-id im Antwort-Header sollten Sie behalten; im Fehlerkörper steht meist ebenfalls eine request_id. Für die Fehlersuche beim Anbieter ist eine Request-ID nützlicher als zehn Screenshots. Logs sollten mindestens Zeitpunkt, Statuscode, Fehlertyp, Modellname und Request-ID enthalten; vollständige Keys und sensible Inhalte gehören nicht hinein.
2. 401 und 403: Auth-Header und Key
401 bedeutet, dass die Identität nicht verifiziert wurde; Guthaben und Modellfähigkeit spielen keine Rolle. Claude Code kennt zwei leicht verwechselbare Variablen: ANTHROPIC_API_KEY wird als X-Api-Key gesendet, ANTHROPIC_AUTH_TOKEN als Authorization: Bearer. Akzeptiert das Gateway nur eine Variante, führt die andere zuverlässig zu 401. Klären Sie zuerst die Anforderung und exportieren Sie nicht beide.
Weitere häufige Ursachen: Leerzeichen, Zeilenumbrüche, Anführungszeichen oder Vollbreitezeichen am Key-Rand; Key gelöscht, abgelaufen oder zu einem anderen Workspace gehörend; Base URL zeigt auf die falsche Umgebung; gleichzeitig Abo-Login und API-Key gesetzt; Unternehmensnetz oder Proxy verändert den Auth-Header.
403 ist meist ein Berechtigungsproblem: Der Key hat das Modell nicht freigeschaltet, keine Projektberechtigung, ist von einer IP-Allowlist blockiert, oder die Workspace-Richtlinie erlaubt den Zugriff nicht. 403 nicht wiederholen; prüfen Sie zuerst Modellfreigaben und Zugriffsrichtlinien in der Konsole.
Schnelle Isolation: Rufen Sie mit demselben Key und derselben Base URL direkt /v1/messages auf. Klappt der Direktaufruf, aber Claude Code scheitert, liegt es an der Client-Konfiguration. Scheitert auch der Direktaufruf, liegt es an Key, Gateway oder Netzwerk.
3. 404: Base-URL-Pfad und Modellname
404 hat zwei Klassen: falscher Pfad oder nicht existierende Ressource. Claude Code nutzt die Anthropic Messages API und erwartet die Base URL üblicherweise als Root-Adresse; den Pfad /v1/messages hängt der Client selbst an. Enthält die Base URL bereits /v1, kann der tatsächliche Pfad /v1/v1/messages lauten.
Prüfen Sie in dieser Reihenfolge:
- Protokoll bestätigen: Claude Code nutzt Anthropic Messages, nicht OpenAI Chat Completions.
- Prüfen, ob
/v1fehlt oder doppelt vorhanden ist. Claude Code bekommt meist die Root-Adresse; OpenAI-kompatible Clients meist eine Adresse mit/v1. - Schrägstrich am Ende und Groß-/Kleinschreibung prüfen, um Doppelschrägstriche oder abgeschnittene Pfade zu vermeiden.
- Den aktuellen Modellnamen aus den Modellpreisen kopieren; Gateway-Aliase können von offiziellen Namen abweichen.
- Mit einer minimalen Anfrage testen, um Proxy und Client-Cache auszuschließen.
Lautet die Meldung model not found, prüfen Sie Modellname und Rechte. Ist es not_found_error und der Pfad offensichtlich falsch, prüfen Sie die Base URL.
4. 429: Ratenlimit, Kontingent und Retry-Sturm
429 bedeutet, dass eine Anfrage Rate, Parallelität oder Ausgabenlimit überschritten hat. Häufige Ursachen: Anfragen oder Tokens pro Minute überschritten; mehrere Dienste teilen einen Key; Retries ohne Backoff erzeugen einen Retry-Sturm; Konto- oder Workspace-Ausgabenlimit erreicht; plötzlich steigender Traffic löst eine Beschleunigungsbremse aus.
Manche 429 durch Ausgabenlimits enthalten kein retry-after; Warten allein hilft dann nicht, das Limit muss angepasst oder Guthaben aufgeladen werden. Prüfen Sie zuerst retry-after; fehlt er, nutzen Sie exponentielles Backoff mit Jitter und eine maximale Retry-Zahl. 401, 403, 404 und 400 nicht wiederholen.
Beachten Sie die Standard-Retries der SDKs: Das offizielle Anthropic-SDK wiederholt Verbindungsfehler, 429 und 5xx zweimal. Kommt eine eigene Retry-Schicht hinzu, summieren sich die tatsächlichen Anfragen. Planen Sie max_retries und fachliche Retries gemeinsam.
429 und 529 sind verschieden: Bei 429 prüfen Sie zuerst eigene Parallelität, Keys und Kontingente; 529 bedeutet Serverüberlastung und erfordert Backoff, weniger Parallelität und einen Blick auf den Dienststatus.
5. 400 und 413: Kontextüberschreitung und zu große Anfragen
Eine Kontextüberschreitung liefert meist 400 invalid_request_error mit einer Meldung wie prompt is too long. Ursache ist nicht ein defektes Modell, sondern ein Budget aus Eingabe plus Ausgabe, das das Kontextfenster übersteigt.
Behandlungsreihenfolge:
- Vor der Anfrage die Eingabe mit
count_tokensmessen, nicht nach Zeichenzahl schätzen. - Die älteste Historie kürzen; nur System, letzte Runden und Zusammenfassung behalten.
- Bei Dokumenten zuerst relevante Fragmente per Retrieval holen, nicht die ganze Sammlung einfügen.
- Lange Dokumente nach Kapiteln aufteilen, abschnittsweise verarbeiten und danach zusammenführen.
- Tool-Ausgaben komprimieren und nur notwendige Felder zurückgeben.
- Platz für die Ausgabe lassen.
max_tokensist nur die Obergrenze der Ausgabe und behebt keine zu große Eingabe.
413 request_too_large bedeutet einen zu großen Request-Body und ist nicht dasselbe wie Kontextlänge. Besonders inline eingebettete Base64-Bilder überschreiten Limits; komprimieren Sie Bilder, nutzen Sie einen Datei-Upload-Endpunkt oder teilen Sie die Anfrage.
400 ist nicht immer ein Kontextproblem. Nicht unterstützte Parameter, ungültige Thinking-Konfiguration oder ein erreichtes Ausgabenlimit können ebenfalls 400 liefern. Lesen Sie type und die konkreten Felder im Fehlerkörper.
6. Timeouts und Abbrüche: Streaming, Proxy und SSL
Das Timeout einer einzelnen Anfrage steuert API_TIMEOUT_MS, standardmäßig 600000 Millisekunden, also 10 Minuten. In langsamen Netzen oder Proxy-Umgebungen lässt es sich erhöhen, aber nicht unbegrenzt; sonst werden Störungen erst sehr spät sichtbar.
Für lange Aufgaben bevorzugen Sie Streaming oder Batch-Endpunkte. Eine nicht gestreamte Anfrage, die voraussichtlich länger als 10 Minuten dauert, kann durch ein Idle-Timeout abgebrochen werden und wirkt wie „hängt“ oder „Timeout“. Streaming erhält laufend Daten und hält die Verbindung stabiler.
Achtung: Eine Streaming-Antwort kann zuerst HTTP 200 liefern und danach im SSE-Eventstrom ein error-Event senden. Ein Client, der nur den Statuscode prüft, hält den Fehler für Erfolg. Parsen Sie Fehlerereignisse im Strom und markieren Sie bereits erzeugte Teile als unvollständig.
Proxy- und Zertifikatsprobleme äußern sich ebenfalls als Timeout: Für einen Unternehmensproxy HTTPS_PROXY oder HTTP_PROXY setzen; bei TLS-Inspektion die entsprechende CA vertrauen, bei Node-Clients häufig über NODE_EXTRA_CA_CERTS; DNS, IPv6, Firewall und MTU können Verbindungen instabil machen, ein Netz- oder Hotspot-Wechsel klärt das schnell. Ist das erste Byte des Gateways langsam, beachten Sie CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS.
7. Logs und Support-Checkliste
Protokollieren Sie nicht nur „es gab einen Fehler“. Sammeln Sie:
- Zeitpunkt, Zeitzone und Dauer.
claude --versionund Betriebssystem.- Base URL (Domain genügt, kein vollständiger Key).
- Modellname, ob Streaming aktiv war, Anfragedauer und Retry-Anzahl.
- HTTP-Statuscode, Fehlertyp und vollständige Fehlermeldung.
request-id, sowohl aus Header als auch aus Body.- Ausmaß: eine Person, ein Netz, ein Projekt oder das ganze Team.
- Minimale Reproduktion: ein curl oder ein minimales Repository; außerdem das Ergebnis derselben Anfrage am offiziellen Endpunkt.
Log-Maskierung muss konkret sein: Vom Key nur die ersten und letzten vier Zeichen behalten; Prompts und Code nach Unternehmensrichtlinie behandeln.
8. Beispiel: Retry abhängig vom Fehlertyp
Das folgende Beispiel wiederholt nur 429, 5xx und Netzwerk-Timeouts; 401 und 404 schlagen sofort fehl, damit aus einem Konfigurationsproblem kein Retry-Sturm wird. Base URL und Modellname kommen aus Umgebungsvariablen.
import os
import random
import time
from anthropic import (
Anthropic,
APIConnectionError,
APIStatusError,
APITimeoutError,
AuthenticationError,
NotFoundError,
RateLimitError,
)
client = Anthropic(
base_url=os.environ["ANTHROPIC_BASE_URL"],
auth_token=os.environ["ANTHROPIC_AUTH_TOKEN"],
)
def ask(prompt: str, retries: int = 4) -> str:
for attempt in range(retries):
try:
resp = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=512,
messages=[{"role": "user", "content": prompt}],
)
return resp.content[0].text
except AuthenticationError as exc:
raise SystemExit(f"401: Key und Auth-Header prüfen, request-id={exc.request_id}") from exc
except NotFoundError as exc:
raise SystemExit(f"404: Base URL und Modellnamen prüfen, request-id={exc.request_id}") from exc
except RateLimitError:
wait = min(2 ** attempt, 20) + random.random()
print(f"429: warte {wait:.1f}s und wiederhole")
time.sleep(wait)
except (APITimeoutError, APIConnectionError):
wait = min(2 ** attempt, 10) + random.random()
print(f"Timeout oder Verbindungsfehler: warte {wait:.1f}s und wiederhole")
time.sleep(wait)
except APIStatusError as exc:
if exc.status_code >= 500:
wait = min(2 ** attempt, 20) + random.random()
print(f"{exc.status_code}: warte {wait:.1f}s und wiederhole")
time.sleep(wait)
continue
raise
raise RuntimeError("Retries erschöpft, auf Fallback oder Alarm umschalten")
print(ask("Antworte nur mit OK"))
Nutzt das Gateway X-Api-Key statt Bearer, ersetzen Sie auth_token= durch api_key= oder passen es gemäß Client-Dokumentation an. Das Beispiel setzt max_retries nicht explizit; das SDK wiederholt weiterhin standardmäßig. In der Produktion sollten Sie beides gemeinsam konfigurieren.
Häufige Fragen
Ist 401 immer ein falscher Key?
Nein. Ein nicht passender Auth-Header, eine Base URL auf die falsche Umgebung oder ein Proxy, der Header umschreibt, erzeugen ebenfalls 401. Testen Sie zuerst denselben Key und dieselbe Base URL direkt und prüfen Sie dann die Client-Variablen.
404 bleibt auch nach Modellwechsel bestehen – was tun?
Prüfen Sie den Base-URL-Pfad. Claude Code erwartet meist die Root-Adresse und hängt /v1/messages selbst an; eine Adresse mit /v1 erzeugt ein doppeltes /v1. Danach den Modellnamen mit der Gateway-Liste abgleichen.
Erholt sich 429 nach kurzer Wartezeit sicher?
Nicht immer. Ratenlimits erholen sich meist, aber ein 429 durch Ausgabenlimit enthält oft kein retry-after; Warten hilft dann nicht, das Limit oder Guthaben muss angepasst werden. Prüfen Sie Fehlertyp und Header.
Gilt eine Streaming-Antwort mit 200 und anschließendem Abbruch als Erfolg?
Nein. Eine Streaming-Antwort kann nach 200 ein Fehlerereignis über SSE senden. Der Client muss den Ereignisstrom parsen und ein reguläres Ende bestätigen; sonst das Ergebnis als unvollständig markieren und wiederholen oder alarmieren.
Mehr Retries bedeuten mehr Stabilität?
Nein. Retries beheben nur vorübergehende Fehler; zu viele vervielfachen Störung und Kosten. Setzen Sie Obergrenze, exponentielles Backoff und Jitter, unterscheiden Sie wiederholbare und nicht wiederholbare Fehler; bei Operationen mit Nebenwirkungen zuerst prüfen, ob sie bereits ausgeführt wurden.
Nächste Schritte
Erstellen Sie im ZSQH AI Gateway einen Test-Key und spielen Sie 401, 404, 429 und Timeout je einmal durch, bevor Sie Produktionsmonitoring anbinden. Modellverfügbarkeit und Abrechnung entnehmen Sie den Modellpreisen.
Weiterlesen:
- Claude Code API-Key einrichten und absichern
- Claude Code einrichten: Installation, Base URL und Modelle
- Claude API einrichten: Key, Base URL und Modelle
Hinweis: Claude, Claude Code und Anthropic sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeit zu den genannten Unternehmen. Fehlertypen und Schnittstellenverhalten können sich mit Versionen ändern; maßgeblich ist die offizielle Dokumentation.
