Errore 401 authentication_error / invalid x-api-key — cosa verificare, nell'ordine

Quasi ogni 401 ha una delle quattro cause, e solo una è «la chiave è errata». Le altre tre lasciano la chiave perfettamente valida; per questo ricrearla è spesso uno spreco di tempo.

L’errore

risposta (HTTP 401)

{
  "type": "error",
  "error": { "type": "authentication_error",
             "message": "invalid x-api-key" }
}

Cause e soluzioni in breve

Causa	Soluzione
Intestazione errata per l'host	Anthropic legge x-api-key; la maggior parte dei gateway compatibili con OpenAI legge Authorization: Bearer. Lo stesso valore inserito nell'intestazione errata viene interpretato come assente.
Vecchia variabile d'ambiente residua	Un'ANTHROPIC_API_KEY dimenticata nel profilo della shell può avere la precedenza su quella appena esportata.
Base URL cambiata senza cambiare la credenziale	Puntare a un altro host non rende lì valida la chiave del provider precedente. Host e credenziale devono cambiare insieme.
Spazio, interruzione di riga o virgolette nella chiave	Copiare da un PDF o da una chat può introdurre caratteri invisibili. Verifica la lunghezza della stringa.

Verifica cosa contiene realmente l'ambiente

Prima di cambiare qualcosa, controlla le variabili nella stessa shell che esegue l'applicazione. Un numero sorprendente di casi presenta due credenziali definite contemporaneamente, appartenenti a provider diversi.

conferir.sh

for v in ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN ANTHROPIC_BASE_URL; do
  printf '%-22s [%s] tamanho=%s\n' \
    "$v" "$(printenv "$v" | cut -c1-10)" "$(printenv "$v" | wc -c)"
done

Testa la credenziale al di fuori dell'applicazione

Una richiesta diretta distingue tra «l'host rifiuta la chiave» e «l'applicazione non invia la chiave». Se curl funziona e il codice no, il problema non è la credenziale.

testar.sh

curl -s -o /dev/null -w 'status=%{http_code}\n' \
  "$ANTHROPIC_BASE_URL/v1/models" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN"

# 200 -> credencial boa; investigue a aplicação
# 401 -> credencial ou cabeçalho errados para este host

Distingui 401, 403 e 402

401 significa «non so chi sei»: la credenziale non è stata accettata. 403 significa «so chi sei, ma non puoi»: autenticato senza autorizzazione. 402 significa «so chi sei, ma manca il saldo». Solo il 401 si risolve intervenendo sulla credenziale.

Se chiami tramite Kunavo

Kunavo legge la chiave sk-kn- sia in Authorization: Bearer sia in x-api-key, e la base URL è l'origine del sito senza alcun percorso successivo. Con Claude Code, usa ANTHROPIC_AUTH_TOKEN insieme ad ANTHROPIC_BASE_URL, perché il token non dipende dall'approvazione unica richiesta da ANTHROPIC_API_KEY, e rimuovi esplicitamente ANTHROPIC_API_KEY: un valore obsoleto in questa variabile è la causa più comune di una sessione apparentemente configurata che continua a rifiutare le richieste. La procedura dettagliata per l'autenticazione è disponibile nella documentazione sull'autenticazione.

Domande frequenti

Ricreare la chiave risolve il problema?

Solo se la chiave è stata effettivamente revocata. Nelle altre tre cause più comuni — intestazione errata, vecchia variabile, base URL cambiata — la nuova chiave fallisce esattamente allo stesso modo.

Un 401 può dipendere dal saldo insufficiente?

No. Il saldo insufficiente produce un 402, con un messaggio che parla di crediti. Il 401 riguarda sempre l'identità.

Funziona con curl ma fallisce nel mio codice. Perché?

Quasi sempre il codice legge un'altra variabile d'ambiente oppure viene eseguito in un'altra shell o in un altro container, dove l'export non è arrivato. Stampa la credenziale mascherata all'interno del processo per verificare.

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.