Claude Code „API Error: bad_response_status_code“ — den zugrunde liegenden Status lesen

Dieser Fehler sagt dir, dass der Aufruf fehlgeschlagen ist, und fast nichts darüber, warum. Die nützlichen Informationen — Statuscode und Nachricht des Anbieters — sind nur ein Debug-Flag entfernt, und jeder Status weist auf eine andere Behebung hin.

Der Fehler

terminal

API Error: bad_response_status_code

(no status, no provider message — the wrapper hides both)

Ursachen und Lösungen im Überblick

Ursache	Lösung
401 / 403 darunter	Abweichende Zugangsdaten oder Header gegenüber einer benutzerdefinierten Base-URL. Prüfe, welche Auth-Variable gesetzt ist.
404 darunter	Entweder ist die Modell-ID bei diesem Host unbekannt oder die Base-URL enthält ein zusätzliches Pfadsegment.
402 darunter	Das Gateway-Wallet ist leer. Lade Guthaben auf; an der Client-Konfiguration ist nichts falsch.
429 / 529 darunter	Rate-Limit erreicht oder Upstream überlastet. Mit Backoff erneut versuchen, statt die Konfiguration zu ändern.
Ein Nicht-JSON-Body mit 200	Ein Captive Portal, Unternehmens-Proxy oder eine Fehlerseite. Der Status kann in Ordnung sein, während der Body trotzdem unbrauchbar ist.

Den Wrapper in einen echten Fehler verwandeln

Die Debug-Ausgabe von Claude Code gibt die Anfrage und die Upstream-Antwort aus. Führe einen fehlschlagenden Aufruf mit aktiviertem Debugging aus und lies die Statuszeile — alles Weitere hängt davon ab, was dort steht.

debug.sh

claude --debug 2>&1 | tee claude-debug.log

grep -iE 'status|http/|error' claude-debug.log | head -20

Denselben Aufruf mit curl reproduzieren

Nimm Base-URL und Zugangsdaten aus dem Tool und stelle die Anfrage direkt. So trennst du in einem Schritt „der Host weist uns zurück“ von „der Client ist fehlerhaft“ — und der rohe Body benennt das Problem meist in Klartext, den der Wrapper verworfen hat.

reproduce.sh

curl -i "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Prüfen, dass die Base-URL keinen abschließenden Pfad enthält

Claude Code hängt seinen eigenen Pfad `/v1/...` an. Eine Base-URL, die bereits mit `/v1` endet, erzeugt `/v1/v1/messages`, worauf jeder Host mit 404 antwortet — wiederum verpackt als bad_response_status_code. Setze nur den Origin.

base-url.sh

# Wrong — doubles the version segment
export ANTHROPIC_BASE_URL="https://api.kunavo.com/v1"

# Right — origin only
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Wenn Sie Kunavo verwenden

Bei Kunavo solltest du die beiden Statuscodes 402 und 401 sofort erkennen: 402 bedeutet, dass das Wallet die Anfrage nicht abdecken kann — Guthaben, nicht Konfiguration — und 401 bedeutet, dass Kunavo keinen verwendbaren sk-kn- Schlüssel erhalten hat. Der Schlüssel wird entweder aus Authorization: Bearer oder x-api-key gelesen. Prüfe daher, was Claude Code tatsächlich gesendet hat: Ein Schlüssel in ANTHROPIC_API_KEY benötigt eine einmalige Bestätigung in einer interaktiven Sitzung und wird nach einer Ablehnung ignoriert, während ANTHROPIC_AUTH_TOKEN sofort verwendet wird. Beide Statuscodes werden mit einem JSON-Body zurückgegeben, der den Grund nennt; das Debug-Log ist daher entscheidend und nicht bloß ein Hinweis. Fehlgeschlagene Anfragen werden nicht berechnet. Welche Variable du setzen solltest und warum, wird erklärt in der Anleitung zu den Auth-Variablen.

Häufig gestellte Fragen

Ist dieser Fehler jemals ein eigener Fehler von Claude Code?

Selten. Es handelt sich um einen Wrapper auf Transportebene: Etwas hat geantwortet, und die Antwort war kein Erfolg. Eine Reproduktion mit curl klärt es — wenn curl ebenfalls fehlschlägt, liegt das Problem nicht beim Client.

Es funktioniert mit der offiziellen API, aber nicht mit meinem Gateway.

Dann liegt der Unterschied bei den Zugangsdaten oder der Base-URL, nicht beim Tool. Prüfe den vom Gateway erwarteten Auth-Header und ob deine Base-URL bereits /v1 enthält.

Soll ich automatisch erneut versuchen?

Erst, wenn du den Status kennst. Ein erneuter Versuch bei 401 oder 404 ist sinnlos; bei 429 oder 529 ist ein erneuter Versuch mit Backoff richtig.