Problemi con le API key

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.

Aggiornato il
  • 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.
Oriveo su iPhone: la schermata dei fornitori, con i fornitori che hai collegato e la spesa del mese.

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.

Guida rapida: 401, 402, 403, 429 e 5xx
CodiceChe cosa significa di solitoBasta aspettare?Che cosa fare
401La chiave è sbagliata: manca un carattere, c’è uno spazio in più, è stata eliminata, oppure è di un altro fornitore o di un’altra regioneNoCopia di nuovo la chiave o creane una nuova; controlla fornitore e regione
402Serve un pagamento: il saldo prepagato o i crediti sono finiti, oppure c’è un problema di fatturazioneNoRicarica, oppure sistema il metodo di pagamento nella pagina di fatturazione del fornitore
403La chiave funziona ma non ha l’autorizzazione: paese o regione non supportati, nessun accesso a quel modello, oppure manca una verificaNoControlla le regioni supportate, i permessi della chiave ed eventuali verifiche
404Il nome del modello o l’indirizzo sono sbagliatiNoScegli un altro modello o controlla l’indirizzo
429Troppe richieste in poco tempo oppure, con alcuni fornitori, saldo a zero o limite di spesa raggiuntoSpesso, se è un limite di richiesteAspetta e riprova; se il messaggio parla di quota, saldo, credito o limite di spesa, ricarica o alza il limite
500–504, 529Un guasto o un sovraccarico dal lato del fornitoreDi solitoRiprova 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.

Perché dice saldo o quota insufficiente?
FornitoreCodice quando il saldo finisceChe cosa dice il messaggioPagina ufficiale
OpenAI429credit_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_errorplatform.claude.com/docs/en/api/errors (codici); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (messaggio)
Google Gemini402 (fatturazione prepagata)payment_required; anche un 403 può indicare un saldo Cloud Billing non pagatoaistudio.google.com/docs/api-errors
OpenRouter402Your account or API key has insufficient creditsopenrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)Non indicatoLe richieste vengono rifiutate quando i crediti prepagati finisconodocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
GroqNon documentatoGroq fattura dopo l’uso; la sua pagina degli errori non elenca errori di saldoconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxNon indicato (codice applicativo 1008)insufficient balanceplatform.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)403Arrearage o isv.OUT_OF_SERVICE (account con pagamenti arretrati)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlowNon documentatoNessun errore di saldo elencatodocs.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 significano i messaggi di errore di Oriveo?
Che cosa mostra OriveoChe cosa significaChe 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 chiaveCopia di nuovo la chiave e aggiornala nelle impostazioni di quel fornitore
Chiave API non validaIl fornitore ha restituito 401 o 403Controlla o sostituisci la chiave; per il 403, controlla regione e permessi
Quota del fornitore raggiuntaIl 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 raggiuntoTroppe richieste per il momento (429)Aspetta un attimo e riprova
Quota gratuita raggiuntaLa quota di oggi di Oriveo Free è esaurita; la tua chiave non c’entraAggiungi la tua API key, oppure aspetta che la quota si rinnovi alle 00:00 UTC
Schermata «Fornitori» di Oriveo con l’elenco dei fornitori collegati, come OpenAI, Z.ai, Groq, Gemini e Anthropic, ognuno con la sua spesa
Apri un fornitore da questo elenco per controllare o sostituire la sua chiave.

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?
Guarda il numero dell’errore. 401: la chiave è sbagliata; 402: saldo o crediti finiti; 403: richiesta non consentita (spesso per regione o permessi); 429: troppe richieste oppure, con alcuni fornitori, saldo a zero.
Che cosa significa l’errore 401 per un’API key?
Il fornitore non riconosce la chiave. Copiala di nuovo senza spazi, controlla che sia del fornitore e della regione che hai scelto, oppure creane una nuova.
Che cos’è l’errore 402 Payment Required?
Il saldo prepagato o i crediti sono finiti, oppure c’è un problema di pagamento. Lo usano DeepSeek, OpenRouter, Mistral, Together, Fireworks e la fatturazione prepagata di Gemini. Ricarica nella pagina di fatturazione del fornitore; aspettare non serve.
L’errore 429 è un limite di richieste o un problema di quota?
Può essere l’uno o l’altro. Di solito è un limite di richieste che si risolve dopo una breve attesa. Ma OpenAI, Kimi e Z.ai restituiscono 429 anche quando il saldo è a zero: se il messaggio parla di quota, saldo o credito, aggiungi credito invece di aspettare.
Perché la mia API key OpenAI dice insufficient_quota?
Il tuo account API di OpenAI non ha più credito prepagato. OpenAI restituisce 429 con il codice credit_balance_exhausted, e il tipo di errore può ancora indicare insufficient_quota. Aggiungi credito nelle impostazioni di fatturazione di OpenAI; una chiave nuova non serve.
Perché la mia nuova API key non funziona anche se l’ho copiata bene?
Di solito perché sull’account non c’è ancora credito o la fatturazione non è configurata, perché la chiave appartiene a un’altra regione, oppure perché l’API non è offerta nel tuo paese. Controlla questi punti prima di creare un’altra chiave.

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.