Un 401 da Claude dipende sempre da una di cinque cause: intestazione errata, tipo di chiave non adatto all'endpoint, variabile d'ambiente malformata, chiave revocata o base URL errato per quella chiave. Esegui la diagnostica seguente e individuerai il problema in meno di un minuto.
L’errore
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}Cause e soluzioni in breve
| Causa | Soluzione |
|---|---|
| Intestazione errata per l'endpoint | L'API nativa di Anthropic richiede x-api-key + anthropic-version; gli endpoint compatibili con OpenAI richiedono Authorization: Bearer. |
| Incompatibilità tra chiave ed endpoint | Le chiavi sk-ant-… funzionano solo con api.anthropic.com; le chiavi del gateway (ad es. sk-kn-…) funzionano solo con il rispettivo URL del gateway. |
| Spazi bianchi o virgolette inseriti nella variabile d'ambiente | Esporta nuovamente senza virgolette o newline; stampa len(key) per rilevare un \n finale dovuto al copia-incolla. |
| Chiave revocata o workspace disabilitato | Genera una nuova chiave nella console e ruotala nel tuo gestore dei segreti. |
Riproduci il problema con curl grezzo (escludendo il tuo SDK dall'equazione)
Se curl funziona ma la tua app no, il problema è nella gestione delle variabili d'ambiente, non nella chiave:
# Native Anthropic wire (works on api.anthropic.com and Kunavo /v1/messages)
curl -s https://api.kunavo.com/v1/messages \
-H "x-api-key: $KUNAVO_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
# OpenAI-compatible wire (Bearer header instead)
curl -s https://api.kunavo.com/v1/chat/completions \
-H "Authorization: Bearer $KUNAVO_API_KEY" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'
# Check the key isn't carrying whitespace
python3 -c "import os; k=os.environ['KUNAVO_API_KEY']; print(repr(k[:12]), len(k))"Abbina il prefisso della chiave all'URL di base
sk-ant-… → api.anthropic.com. sk-kn-… → api.kunavo.com/v1. Inviare una chiave del gateway ad Anthropic (o viceversa) restituisce sempre 401: il messaggio di errore non dice mai "wrong host", quindi il problema può passare inosservato.
Ruota la chiave se è mai comparsa in un repository o in un log
Se la chiave è corretta ma viene ancora rifiutata, considera probabile la revoca (gli scanner automatici revocano rapidamente le chiavi esposte). Generane una nuova e conservala in un gestore dei segreti invece che in file .env soggetti al commit.
Se chiami tramite Kunavo
Le chiavi Kunavo (sk-kn-…) si autenticano con entrambe le intestazioni su ogni endpoint: Authorization: Bearer, come le inviano gli SDK OpenAI, oppure x-api-key, come fanno gli SDK Anthropic. Quindi, qualunque SDK utilizzi, cambia solo l'URL di base. Le chiavi vengono create e revocate istantaneamente nella dashboard. Una volta autenticata la chiave, le tariffe applicate sono indicate in tabella dei prezzi dell’API Claude di Anthropic.
Domande frequenti
Perché la mia chiave funziona con curl ma non nella mia app?
Quasi sempre si tratta della gestione delle variabili d'ambiente: un newline finale dovuto al copia-incolla, virgolette incluse nel valore, la variabile non esportata al processo oppure una variabile d'ambiente diversa caricata in produzione. Stampa repr e lunghezza della chiave all'interno del processo che fallisce.
Posso usare la mia chiave della Console Anthropic su un gateway compatibile con OpenAI?
No. Ogni servizio autentica solo le proprie chiavi: le chiavi sk-ant appartengono ad api.anthropic.com, mentre le chiavi del gateway appartengono al gateway. Ottieni una chiave dall'URL di base che stai chiamando.
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.