Claude Code "API Error: bad_response_status_code" — leggere lo status sottostante

Questo errore comunica che la chiamata è fallita e quasi nulla sul motivo. Le informazioni utili — codice di stato e messaggio del provider — sono a un flag di debug di distanza, e ogni status indica una correzione diversa.

L’errore

terminal

API Error: bad_response_status_code

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

Cause e soluzioni in breve

Causa	Soluzione
401 / 403 sottostanti	Credenziali o intestazioni non corrispondenti rispetto a un base URL personalizzato. Controlla quale variabile di autenticazione è impostata.
404 sottostante	L'id del modello è sconosciuto a quell'host oppure il base URL contiene un segmento di percorso aggiuntivo.
402 sottostante	Il portafoglio del gateway è vuoto. Ricarica il saldo: non c'è nulla di errato nella configurazione del client.
429 / 529 sottostanti	Limitazione della frequenza o saturazione dell'upstream. Riprova con backoff invece di riconfigurare.
Corpo non JSON con status 200	Un captive portal, un proxy aziendale o una pagina di errore. Lo status può essere corretto mentre il corpo resta inutilizzabile.

Trasforma il wrapper in un errore reale

L'output di debug di Claude Code stampa la richiesta e la risposta upstream. Esegui una chiamata fallita con il debug attivo e leggi la riga dello status: tutto ciò che segue dipende da quello che indica.

debug.sh

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

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

Riproduci la stessa chiamata con curl

Estrarre il base URL e la credenziale dallo strumento e inviare direttamente la richiesta. Questo separa in un solo passaggio "l'host ci rifiuta" da "il client è malformato"; il corpo grezzo di solito indica il problema con parole semplici che il wrapper ha scartato.

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"}]}'

Verifica che il base URL non abbia un percorso finale

Claude Code aggiunge il proprio percorso `/v1/...`. Un base URL che termina già con `/v1` produce `/v1/v1/messages`, a cui qualsiasi host risponde con 404, nuovamente racchiuso come bad_response_status_code. Imposta solo l'origine.

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"

Se chiami tramite Kunavo

Per Kunavo, i due stati da riconoscere immediatamente sono 402 e 401: 402 significa che il wallet non può coprire la richiesta — è un problema di saldo, non di configurazione — mentre 401 significa che Kunavo non ha ricevuto una chiave sk-kn- utilizzabile. La chiave viene letta da Authorization: Bearer oppure da x-api-key, quindi controlla cosa ha effettivamente inviato Claude Code: una chiave in ANTHROPIC_API_KEY richiede un'approvazione una tantum in una sessione interattiva e viene ignorata se rifiutata, mentre ANTHROPIC_AUTH_TOKEN viene utilizzata immediatamente. Entrambi gli stati restituiscono un corpo JSON che indica il motivo, quindi il log di debug è decisivo, non solo indicativo. Le richieste che falliscono non vengono addebitate. Quale variabile impostare e perché è spiegato in la guida alle variabili di autenticazione.

Domande frequenti

È mai un bug di Claude Code?

Raramente. È un wrapper a livello di trasporto: qualcosa ha risposto e la risposta non indicava un successo. Riprodurre il problema con curl chiarisce la situazione: se anche curl fallisce, il client non è il problema.

Funziona con l'API ufficiale, ma non con il mio gateway.

Allora la differenza sta nelle credenziali o nell'URL di base, non nello strumento. Controlla l'header di autenticazione richiesto dal gateway e verifica se l'URL di base contiene già /v1.

Devo riprovare automaticamente?

Solo dopo aver verificato lo stato. Riprovare con 401 o 404 è inutile; riprovare con 429 o 529 usando il backoff è corretto.

Guide correlate

Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.