Fehlertabelle: häufige Fehler von Claude Code und Codex an einer Gateway-API

Wie Sie diese Tabelle nutzen

Suchen Sie nicht zuerst im Fehlertext nach der Antwort, sondern bestimmen Sie, welche Schicht betroffen ist. Fehler von KI-Clients kommen fast immer aus diesen fünf Schichten:

1. Netzwerkschicht: Die Anfrage hat den Server gar nicht erreicht
2. Authentifizierungsschicht: Sie kam an, aber der Key wird nicht akzeptiert
3. Protokollschicht: Key akzeptiert, aber Pfad oder Format stimmen nicht
4. Modellschicht: Das Protokoll läuft, aber das Modell existiert nicht
5. Kontextschicht: Das Modell läuft, aber die Eingabe ist zu lang

Der Wert dieser Gliederung: Jede Schicht hat eine völlig andere Behebung, und am Fehlertext ist oft nicht zu erkennen, um welche Schicht es geht.

Diagnose nach HTTP-Status

Diese Befehle prüfen die Modellliste und drei Protokolle und zeigen für jede Anfrage den HTTP-Status an:

Den eigenen KimiSeek-API-Key im selben Terminal setzen, in dem curl ausgeführt wird, und den Platzhalter ersetzen. Im Client gespeicherte Zugangsdaten setzen diese Shell-Variable nicht automatisch:

# Replace the placeholder with your own key from the dashboard.
export KIMISEEK_API_KEY="ks-your-key"

# Inspect each HTTP status and error body; a model list does not prove sufficient balance.
# 1. Is the key valid at all? (lists models)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/models\n' https://api.kimiseek.app/v1/models \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}"

# 2. OpenAI Chat Completions
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/chat/completions\n' https://api.kimiseek.app/v1/chat/completions \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

# 3. Anthropic Messages (the protocol Claude Code speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/messages\n' https://api.kimiseek.app/v1/messages \
  -H "x-api-key: ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","max_tokens":8,"messages":[{"role":"user","content":"ping"}]}'

# 4. OpenAI Responses (the protocol Codex speaks)
curl -sS --max-time 30 -w '\nHTTP %{http_code} /v1/responses\n' https://api.kimiseek.app/v1/responses \
  -H "Authorization: Bearer ${KIMISEEK_API_KEY:?Set KIMISEEK_API_KEY before running this command}" \
  -H "Content-Type: application/json" \
  -d '{"model":"deepseek-v4-pro-0813","input":"ping","max_output_tokens":16}'

Den HTTP-Status nach jeder Antwort sowie error.code, error.type und message im Antworttext prüfen. Der fehlgeschlagene Schritt allein belegt keine fehlende Protokollunterstützung. Eine Modellliste mit 200 bestätigt den Schlüssel, nicht das Guthaben: Ohne Guthaben kann Schritt 1 mit 200 und Schritt 2 mit 402 antworten.

Claude-Code-Seite

Keine Zugangsdaten

Invalid API key · Please run /login

Diese Meldung heißt, dass Claude Code keine Zugangsdaten bekommen hat. Prüfen Sie, ob ANTHROPIC_AUTH_TOKEN in der Shell gilt, aus der Claude Code gestartet wurde – ein häufiger Fehler ist, in Terminal A zu exportieren und in Terminal B zu starten.

401 Authentifizierung fehlgeschlagen

API Error: 401 {"type":"error","error":{"type":"authentication_error","message":"invalid api key"}}

Ursachen nach Wahrscheinlichkeit:

1. Beim Kopieren des Keys sind Leerzeichen oder Zeilenumbrüche mitgekommen
2. Der Key wurde gesperrt oder das Kontingent ist erschöpft
3. ANTHROPIC_API_KEY ist gesetzt, aber leer, und der Client fällt auf den Anmeldestatus zurück

403 forbidden

API Error: 403 {"type":"error","error":{"type":"forbidden","message":"invalid x-api-key"}}

Direkt bedeutet diese Meldung meist, dass der Key ungültig ist; über ein Gateway ist die häufigere Ursache eine falsche Schreibweise des Headers: Manche Gateways akzeptieren nur Authorization: Bearer, andere nur x-api-key. KimiSeek akzeptiert beides, aber wenn Sie dazwischen noch einen Proxy gelegt haben, kann der Header umgeschrieben werden.

model not found

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"model: deepseek-v4-flash-0731 not found"}}

Zwei Möglichkeiten: Der Modellname ist falsch geschrieben, oder Sie haben ein abgeschaltetes Modell verwendet. Eine abgeschaltete Modell-id meldet dauerhaft not found, statt auf die Abschaltung hinzuweisen – das ist die Falle, die am meisten Zeit kostet: Sie prüfen lange die Konfiguration, dabei wurde das Modell einfach abgelöst.

Ersetzen Sie sie auf der Modellseite durch eine echte id.

Streaming-Antwort bricht mittendrin ab

API Error: stream disconnected before completion: stream closed before completion

Die Streaming-Verbindung wurde unterwegs abgeschnitten. Prüfen Sie in dieser Reihenfolge:

1. ob ein lokaler HTTP-Proxy (HTTPS_PROXY) dazwischenfunkt
2. ob das Firmennetz bei Antworten in eine Zeitüberschreitung läuft
3. ob serverseitig ein Zeitlimit pro Anfrage gegriffen hat

Das Zeitlimit für die Anfrage an den Upstream beträgt 600 Sekunden bei /v1/messages (Claude Code) und 175 Sekunden bei /v1/responses (Codex). Clients oder zwischengeschaltete Proxys können die Verbindung früher trennen; prüfen Sie den verwendeten Endpoint und die Fehlerdetails.

Kontext überschritten

API Error: 400 {"type":"error","error":{"type":"invalid_request_error","message":"prompt is too long: 210000 tokens > 200000 maximum"}}

Beachten Sie, dass die 200000 hier die Obergrenze des Clients oder des Modells ist, nicht die Zahl, die Sie im Kopf haben. Mit DeepSeek V4 Pro liegt die tatsächliche Grenze bei 1M; sehen Sie 200000, dann ist die Anfrage nicht beim Zielmodell angekommen, oder der Client hat nach der Spezifikation von Claude selbst abgeschnitten.

Codex-Seite

401 Missing bearer

■ unexpected status 401 Unauthorized: Missing bearer

env_key in config.toml ist nur der Variablenname, der echte Wert muss in der Umgebung stehen. Diese Meldung heißt genau: „Der Variablenname ist da, die Umgebungsvariable ist leer.“

404 Not Found

■ unexpected status 404 Not Found

In acht von zehn Fällen fehlt /v1 in der base_url. Codex baut base_url + "/responses"; ohne /v1 landet die Anfrage auf einem Pfad der Website.

Nach base_url auch im Antworttext prüfen, ob das Modell fehlt. Bietet das Gateway tatsächlich kein /v1/responses, ein kompatibles Gateway oder eine Übersetzungsschicht verwenden; aktuelles Codex lehnt wire_api = "chat" ab. Siehe Codex-Anleitung.

Stream-Abbruch

■ stream disconnected before completion

Dasselbe Streaming-Problem wie bei Claude Code, aber Codex reagiert empfindlicher darauf – seine Ausführungsschleife hängt an einem vollständigen Event-Stream. Bei instabilem Netz wechseln Sie lieber das Netz, statt auf Wiederholungen zu setzen.

Zwei typische Fälle der Netzwerkschicht

fetch failed
ECONNREFUSED 127.0.0.1:7890

fetch failed ist der allgemeine Netzwerkfehler von Node und sagt von sich aus nichts aus. Die konkrete Ursache steht in der Zeile mit ECONNREFUSED – zeigt sie auf einen lokalen Port wie 127.0.0.1:7890, dann hat ein lokaler Proxy die Anfrage übernommen, und der Proxy läuft nicht oder seine Regeln stimmen nicht.

Dieser Fall wird am häufigsten als „das Gateway ist down“ fehldiagnostiziert. Der Test: Wenn curl funktioniert und der Client nicht, unterscheiden sich die Umgebungsvariablen der Shell, in der der Client läuft, von denen der Shell, in der curl läuft.

Dieselbe Meldung, andere Ursache

Das ist das Denkmodell, das Sie beim Arbeiten über ein Gateway am meisten brauchen:

Was Sie bei einer Meldung mitgeben sollten

Wenn Sie jemanden fragen (oder ein Ticket anlegen), sind die folgenden vier Dinge unverzichtbar, sonst kann niemand die Ursache eingrenzen:

1. der vollständige Fehlertext (eine ganze Zeile, kein halber Screenshot)
2. das Ergebnis des schichtweisen curl-Tests – welcher der vier Schritte fehlgeschlagen ist
3. die Client-Version (claude --version / codex --version)
4. die verwendete Modell-id und Base URL (Key unkenntlich gemacht)

Prüfdatum

• Prüfdatum: 2026-10-26
• Die Beispiele helfen bei der Fehlersuche; der genaue Wortlaut kann je nach Client-Version abweichen. Bei einer Meldung die installierte Version angeben. Die Codex-Konfiguration wurde mit 0.154.0 geprüft.