La tua API key non funziona? Errori 401, 402, 403 e 429
Perché un’API key di IA smette di funzionare: cosa significano 401, 402, 403 e 429, quale codice usa ogni fornitore per il saldo esaurito e come risolverli.
- Quando un’API key di IA «non funziona», il numero dell’errore ti dice perché: 401 significa che la chiave è sbagliata, 402 di solito che saldo o crediti sono finiti, 403 che la chiave non ha il permesso per quell’operazione, e 429 che le richieste sono troppe oppure, con alcuni fornitori, che il saldo è a zero.
- I fornitori non usano lo stesso codice per il saldo esaurito. DeepSeek, OpenRouter, Mistral, Together, Fireworks e la fatturazione prepagata di Gemini usano 402; OpenAI, Kimi e Z.ai usano 429; Qwen di Alibaba Cloud usa 403. Leggi il messaggio, non solo il numero.
- Gli errori di saldo non spariscono se aspetti; i limiti di richieste di solito sì. La tabella qui sotto riporta la pagina ufficiale degli errori di ogni fornitore, verificata il 18 novembre 2026.

Che cosa vuol dire davvero «l’API key non funziona»?
Un’API key (chiave API) è il codice segreto che un’app invia con ogni richiesta, così il fornitore di IA sa che sei tu e a quale account addebitare i costi. Quando qualcosa va storto, il fornitore risponde con un errore: un numero di tre cifre chiamato codice di stato HTTP, più un breve messaggio.
Il numero indica il tipo di problema; il messaggio aggiunge i dettagli. Oriveo trasforma gli errori più comuni in titoli chiari, come «Chiave API non valida» o «Quota del fornitore raggiunta», spiegati più avanti in questa pagina.
Guida rapida: 401, 402, 403, 429 e 5xx
Parti da qui: trova il tuo numero, poi leggi la sezione corrispondente più sotto. Questo riepilogo segue le pagine degli errori di OpenAI, Anthropic e degli altri fornitori al 18 novembre 2026.
| Codice | Che cosa significa di solito | Basta aspettare? | Che cosa fare |
|---|---|---|---|
| 401 | La chiave è sbagliata: manca un carattere, c’è uno spazio in più, è stata eliminata, oppure è di un altro fornitore o di un’altra regione | No | Copia di nuovo la chiave o creane una nuova; controlla fornitore e regione |
| 402 | Serve un pagamento: il saldo prepagato o i crediti sono finiti, oppure c’è un problema di fatturazione | No | Ricarica, oppure sistema il metodo di pagamento nella pagina di fatturazione del fornitore |
| 403 | La chiave funziona ma non ha l’autorizzazione: paese o regione non supportati, nessun accesso a quel modello, oppure manca una verifica | No | Controlla le regioni supportate, i permessi della chiave ed eventuali verifiche |
| 404 | Il nome del modello o l’indirizzo sono sbagliati | No | Scegli un altro modello o controlla l’indirizzo |
| 429 | Troppe richieste in poco tempo oppure, con alcuni fornitori, saldo a zero o limite di spesa raggiunto | Spesso, se è un limite di richieste | Aspetta e riprova; se il messaggio parla di quota, saldo, credito o limite di spesa, ricarica o alza il limite |
| 500–504, 529 | Un guasto o un sovraccarico dal lato del fornitore | Di solito | Riprova più tardi o cambia modello |
Perché dice saldo o quota insufficiente?
Quasi tutti i fornitori chiedono credito prepagato o un metodo di pagamento attivo prima che l’API funzioni, e ognuno segnala il saldo esaurito a modo suo. Una chiave nuova non risolve nessuno di questi casi; aggiungere credito sì.
Ecco il codice che ciascuno dei 15 fornitori integrati in Oriveo documenta quando saldo o credito finiscono. «Non indicato» significa che la documentazione del fornitore, verificata il 18 novembre 2026, non dà un codice HTTP per questo caso.
| Fornitore | Codice quando il saldo finisce | Che cosa dice il messaggio | Pagina ufficiale |
|---|---|---|---|
| OpenAI | 429 | credit_balance_exhausted (il tipo di errore può ancora essere insufficient_quota) | developers.openai.com/api/docs/guides/error-codes |
| Anthropic (Claude) | Non indicato | «Your credit balance is too low to access the Anthropic API»; i problemi di pagamento restituiscono 402 billing_error | platform.claude.com/docs/en/api/errors (codici); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (messaggio) |
| Google Gemini | 402 (fatturazione prepagata) | payment_required; anche un 403 può indicare un saldo Cloud Billing non pagato | aistudio.google.com/docs/api-errors |
| OpenRouter | 402 | Your account or API key has insufficient credits | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI (Grok) | Non indicato | Le richieste vengono rifiutate quando i crediti prepagati finiscono | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | Non documentato | Groq fattura dopo l’uso; la sua pagina degli errori non elenca errori di saldo | console.groq.com/docs/errors |
| Together AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | Non indicato (codice applicativo 1008) | insufficient balance | platform.minimax.io/docs/api-reference/errorcode |
| Z.ai (GLM) | 429 (codice 1113) | Insufficient balance or no resource package. Please recharge. | docs.z.ai/api-reference/api-code |
| Qwen (Alibaba Cloud) | 403 | Arrearage o isv.OUT_OF_SERVICE (account con pagamenti arretrati) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi (Moonshot AI) | 429 | exceeded_current_quota_error | platform.kimi.ai/docs/api/errors |
| SiliconFlow | Non documentato | Nessun errore di saldo elencato | docs.siliconflow.com/en/faqs/error-code |
401: API key non valida o autenticazione fallita
Un 401 significa che il fornitore non riconosce la chiave. I messaggi tipici sono «Incorrect API key provided» (OpenAI), «authentication_error» (Anthropic), «Authentication Fails» (DeepSeek) e «Invalid API key: this is not an OpenRouter API key» (OpenRouter).
- Copia di nuovo la chiave dal sito del fornitore e controlla che non manchino caratteri e che non ci siano spazi all’inizio o alla fine.
- Verifica che la chiave appartenga al fornitore che hai scelto. Una chiave OpenAI non funziona come chiave OpenRouter, e viceversa.
- Kimi, MiniMax e Qwen hanno piattaforme regionali separate, e la chiave di una piattaforma non funziona sulle altre. In Oriveo scegli la regione giusta nel selettore «Endpoint ufficiale» («URL della richiesta ufficiale» su iPhone).
- Se la chiave è stata eliminata o revocata, oppure è scaduta, creane una nuova.
402: pagamento richiesto o saldo insufficiente
Un 402 è una questione di soldi: il saldo prepagato è a zero, oppure il metodo di pagamento non è andato a buon fine. Ricarica o aggiorna i dati di pagamento nella pagina di fatturazione del fornitore, poi invia di nuovo. Aspettare non serve.
In Oriveo compare come «Quota del fornitore raggiunta»: «Il fornitore segnala che la quota o il credito di questa chiave API è esaurito. Controlla la fatturazione presso il fornitore oppure cambia modello.»
403: accesso vietato o permessi insufficienti
Un 403 significa che il fornitore ha riconosciuto la chiave ma non consente la richiesta. Il motivo dipende dal fornitore:
- OpenAI restituisce «Country, region, or territory not supported» quando l’API viene usata da un paese che non supporta. Ogni fornitore pubblica l’elenco dei paesi supportati.
- Gemini restituisce 403 quando un progetto del livello gratuito deve essere verificato (FREE_TIER_VERIFICATION_REQUIRED), quando l’account Cloud Billing collegato ha un saldo non pagato, oppure quando Google ha bloccato una chiave segnalata come trapelata.
- Anthropic restituisce permission_error quando la chiave non può usare la risorsa richiesta; controlla le impostazioni dell’organizzazione e del workspace.
- OpenRouter restituisce 403 quando una richiesta viene bloccata da permessi, moderazione, un guardrail o un limite di budget.
- SiliconFlow richiede la verifica dell’identità per alcuni modelli.
- Qwen usa il 403 sia per un account con pagamenti arretrati sia, con il codice AllocationQuota.FreeTierOnly, quando la quota gratuita è esaurita ed è attiva l’impostazione «Free Quota Only».
429: troppe richieste, rate limit o quota superata
Nella maggior parte dei casi un 429 significa che hai inviato troppe richieste o troppi token in poco tempo. È un limite di richieste (rate limit) e si risolve aspettando qualche decina di secondi. Se la risposta indica un tempo di attesa Retry-After, aspetta quanto indicato.
Diversi fornitori usano il 429 anche per il saldo esaurito o per un limite di spesa, e in quei casi aspettare non serve: OpenAI (credit_balance_exhausted, oppure un limite di spesa che hai impostato tu), Kimi (exceeded_current_quota_error), Z.ai (codice 1113) e Anthropic quando un’organizzazione raggiunge il limite di spesa mensile (enforced_spend_limit_reached), che resta attivo fino al mese successivo, a meno che tu non chieda un livello superiore.
I livelli gratuiti sono più stretti. Il livello gratuito di Gemini e i modelli gratuiti di OpenRouter hanno limiti al minuto e al giorno.
In Oriveo il limite di richieste compare come «Limite di richieste raggiunto» sul web o «Limite di richieste del fornitore raggiunto» su iPhone e Android. Se il messaggio parla di quota o credito, Oriveo mostra invece «Quota del fornitore raggiunta».
Che cosa significano i messaggi di errore di Oriveo?
Ecco i messaggi che puoi vedere in Oriveo, con il testo che compare nell’app in italiano:
| Che cosa mostra Oriveo | Che cosa significa | Che cosa fare |
|---|---|---|
| Salvato, ma la chiave sembra non valida. Puoi verificarla più tardi nelle impostazioni del fornitore. | Oriveo ha salvato il fornitore, ma durante la verifica il fornitore ha rifiutato la chiave | Copia di nuovo la chiave e aggiornala nelle impostazioni di quel fornitore |
| Chiave API non valida | Il fornitore ha restituito 401 o 403 | Controlla o sostituisci la chiave; per il 403, controlla regione e permessi |
| Quota del fornitore raggiunta | Il fornitore dice che il credito o la quota di questa chiave sono esauriti (402, oppure 429 con un riferimento alla quota) | Ricarica presso il fornitore, oppure passa a un altro modello |
| Limite di richieste raggiunto / Limite di richieste del fornitore raggiunto | Troppe richieste per il momento (429) | Aspetta un attimo e riprova |
| Quota gratuita raggiunta | La quota di oggi di Oriveo Free è esaurita; la tua chiave non c’entra | Aggiungi la tua API key, oppure aspetta che la quota si rinnovi alle 00:00 UTC |

Usi un endpoint personalizzato, un servizio intermediario o un gateway?
Se ti colleghi tramite un endpoint personalizzato, l’errore può venire da quel servizio o dal fornitore che c’è dietro. Quando Oriveo dice «Questa connessione non ha raggiunto il fornitore a monte», l’account che il servizio ha presso il fornitore potrebbe non essere valido, essere senza credito o aver raggiunto un limite di richieste. Non dipende dalla tua configurazione: passa a un’altra connessione o contatta chi gestisce il servizio.
Controlla questi punti prima di creare una chiave nuova
Una chiave nuova risolve un 401 e poco altro. Prima passa in rassegna questo elenco:
- Hai scelto il fornitore giusto e, per Kimi, MiniMax, Qwen, SiliconFlow e Z.ai, anche la regione giusta.
- Hai copiato la chiave intera, senza spazi.
- Sull’account c’è credito, oppure un metodo di pagamento attivo.
- Il tuo paese o la tua regione sono nell’elenco di quelli supportati dal fornitore.
- Il modello che hai scelto è disponibile per il tuo account o per il tuo livello.
Domande frequenti
Perché la mia API key non funziona?
Che cosa significa l’errore 401 per un’API key?
Che cos’è l’errore 402 Payment Required?
L’errore 429 è un limite di richieste o un problema di quota?
Perché la mia API key OpenAI dice insufficient_quota?
Perché la mia nuova API key non funziona anche se l’ho copiata bene?
Letture correlate
Errori spiegati in modo chiaro, per ogni chiave
Apri l’app web o scarica Oriveo per iPhone o Android, aggiungi le chiavi di 15 fornitori e scopri con chiarezza il motivo quando una richiesta non va a buon fine.
Non hai ancora una chiave API? Con Oriveo Free puoi iniziare senza.