Errore API 401 o 404: chiave, base URL o id del modello sbagliati

La tua richiesta è fallita con un codice di stato e non sai da dove iniziare. Risposta breve: 401 di solito indica la chiave, 404 di solito significa che stai bussando nel posto sbagliato — o l'indirizzo (base URL e path) o l'id del modello. Tre cose da controllare, in questo ordine, e un comando curl che dimostra la correzione.

La pagina dei codici di errore di OpenAI (consultata il 26 ottobre 2026) elenca due messaggi 401: "Invalid Authentication" e "Incorrect API key provided". La soluzione indicata è la stessa per entrambi: controlla la chiave o generane una nuova. La pagina non documenta alcun 404 per l'API stessa, quindi per il 404 la regola seguente deriva da come funzionano gli endpoint compatibili con OpenAI, non da quella pagina.

Il modo rapido per distinguerli#

La formulazione del messaggio dipende dal server e dal tuo strumento (Cline, Aider, OpenCode e Continue incapsulano gli errori ognuno a modo proprio), quindi parti dal numero, poi conferma con il controllo curl qui sotto.

401: la chiave non corrisponde all'endpoint#

La storia classica: hai spostato uno strumento su un nuovo provider, hai cambiato il base URL e hai lasciato la chiave del vecchio provider nella configurazione. L'indirizzo è nuovo, la chiave è vecchia, e il server risponde 401. Nulla è rotto; la chiave appartiene semplicemente a un'altra casa.

Cosa controllare:

1. Quale provider ha emesso la chiave? Deve essere quello di cui stai chiamando l'indirizzo. Una chiave per un servizio non è valida su un altro.
2. Caratteri estranei. Uno spazio o un'interruzione di riga incollati con la chiave, o virgolette finite dentro il valore.
3. Da dove la legge lo strumento. Una variabile d'ambiente impostata in un terminale e non in quello da cui è partito il tuo editor è una causa frequente. Se lo strumento ha sia un file di configurazione sia una variabile d'ambiente, scopri quale ha la precedenza.
4. Una chiave revocata o eliminata. Una chiave che hai eliminato o revocato smette di funzionare — creane una nuova e mettila nella configurazione.

Se non sei sicuro di come funzionano le chiavi o di dove conservarle, cos'è una chiave API e come conservarla in sicurezza lo spiega in parole semplici.

404 su ogni modello: l'indirizzo è sbagliato#

Il base URL per CheapTokens è https://api.cheaptokens.dev/v1. Gli strumenti e gli SDK aggiungono da soli il path dell'endpoint, quindi gli errori tipici riguardano /v1:

• /v1 mancante: lo strumento finisce per chiamare https://api.cheaptokens.dev/chat/completions.
• /v1 raddoppiato: hai incollato il path completo in un campo che lo aggiunge già, e ottieni https://api.cheaptokens.dev/v1/v1/chat/completions.
• Variante sbagliata: gli strumenti in stile OpenAI e l'SDK OpenAI prendono l'indirizzo con /v1. L'SDK Anthropic e Claude Code prendono l'indirizzo senza /v1: https://api.cheaptokens.dev.

Se ti sei mai chiesto cos'è esattamente un base URL e quale parte aggiunge lo strumento, questa spiegazione lo ripercorre. Per il lato Anthropic, vedi l'SDK Python di Anthropic con CheapTokens.

404 su un modello: l'id del modello#

Questo coglie chi copia un nome da una tabella dei prezzi o da un altro provider. Una tabella dei prezzi potrebbe dire DeepSeek-V4-Flash; l'API vuole l'id completo del gateway, con il prefisso dello sviluppatore e la release:

Gli id brevi delle etichette dei prezzi non sono accettati dall'API, e l'ortografia conta: lettere maiuscole, la barra, il suffisso -0731. Copia l'id dalla documentazione di CheapTokens invece di digitarlo a memoria — provider diversi chiamano lo stesso modello in modi diversi. Per vedere gli id esatti disponibili per la tua chiave, chiama GET https://api.cheaptokens.dev/v1/models con lo stesso header Authorization e copia l'id dalla lista:

curl https://api.cheaptokens.dev/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Se la logica dei nomi nella tabella sembra strana, come leggere i nomi dei modelli AI spiega la differenza tra alias e versione bloccata.

Dimostra la correzione con un comando curl#

Togli lo strumento dall'equazione e chiama l'API direttamente. Sostituisci il segnaposto della chiave con la tua:

curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "messages": [{"role": "user", "content": "Say hi in one word."}],
    "max_tokens": 20
  }'

Questa singola richiesta contiene tutti e tre i sospetti: la chiave nell'header, il base URL nella prima riga, l'id del modello nel body. Una risposta JSON con un array choices significa che tutti e tre sono corretti, e qualunque cosa faccia diversamente il tuo strumento è il problema. Se fallisce, cambia una cosa alla volta:

• 401 → sostituisci con la chiave ottenuta da CheapTokens e riesegui.
• 404 → confronta l'URL carattere per carattere con quello sopra, poi l'id del modello.

Dopo che curl funziona, copia gli stessi tre valori nello strumento: la chiave, il base URL (https://api.cheaptokens.dev/v1, o senza /v1 per l'SDK Anthropic e Claude Code) e l'id completo del modello.

Se ancora non funziona#

• Stesso errore nello strumento, curl va bene. Lo strumento sta leggendo una vecchia chiave o un vecchio URL da qualche altra parte: un secondo file di configurazione, un profilo salvato, una variabile d'ambiente. Riavvia lo strumento dopo averlo modificato.
• Non sei sicuro che l'id del modello sia giusto. Chiama GET /v1/models con la tua chiave e copia l'id dalla lista.
• Connessione rifiutata, timeout, errori di certificato. Non è un 401 o un 404; vedi errori di connessione comuni.
• Non sei sicuro di come debba essere la prima richiesta. La tua prima richiesta API procede passo passo, e la documentazione ha il riferimento completo.

L'abitudine da mantenere: quando una chiamata fallisce, leggi prima il numero. 401 di solito significa la chiave, 404 di solito l'indirizzo o l'id del modello, e curl risolve la questione. Così si sistemano la maggior parte di questi errori prima ancora di aprire un singolo log.