«Il modello è sovraccarico» è l’unico errore di Gemini che non dipende da te: il pool di distribuzione di quel modello al momento non ha capacità disponibile. Nulla nelle impostazioni del progetto può impedirlo; puoi solo gestirlo con la massima fluidità possibile e scegliere il fallback da usare quando il tentativo non riesce.
L’errore
{
"error": {
"code": 503,
"message": "The model is overloaded. Please try again later.",
"status": "UNAVAILABLE"
}
}Cause e soluzioni in breve
| Causa | Soluzione |
|---|---|
| Picco di domanda nel pool di distribuzione del modello | Backoff esponenziale con jitter; il picco normalmente passa in pochi secondi o qualche minuto. |
| Varianti di modelli in anteprima o sperimentali | Le build -exp e preview vengono eseguite su pool piccoli e si sovraccaricano per prime. In produzione, fissa l’alias stabile. |
| Richieste pesanti nelle ore di punta | Contesti enormi e limiti massimi dell’output vengono eliminati più facilmente sotto carico: riduci ciò che non ti serve e trasmetti la risposta in streaming. |
Conferma che sia 503 UNAVAILABLE, non 429
429 RESOURCE_EXHAUSTED riguarda la tua quota; 503 UNAVAILABLE riguarda la capacità di Google. La distinzione determina tutto ciò che segue: gli errori di quota richiedono modifiche alla fatturazione o ai limiti, quelli di capacità richiedono retry e fallback. Non eseguire il debug delle impostazioni del progetto per un 503: non c’è nulla da trovare lì.
Riprova con il backoff, ma con un budget
503 è ritentabile per definizione. Usa lo stesso backoff esponenziale con jitter previsto per qualsiasi 429 (lo snippet nella nostra guida ai 429 di Claude funziona senza modifiche: ritenta già gli stati della classe 500), ma limita l’attesa totale a ciò che il chiamante può assorbire; se un sovraccarico supera circa 5 tentativi nell’arco di un minuto, non passerà rapidamente.
Quando i retry si esauriscono: cambia modello, non il ciclo
Prepara una catena di fallback prima di averne bisogno: l’alias stabile se stavi usando una build preview, gemini-2-5-flash se quello in difficoltà è 2.5 Pro (o viceversa), oppure un provider completamente diverso per la richiesta che non deve fallire. I fallback trasformano un’interruzione in un downgrade della qualità.
Se chiami tramite Kunavo
Questa modalità di errore è il motivo per cui Kunavo ritenta all’interno della richiesta: quando per un modello è configurato più di un canale upstream, un tentativo fallito passa all’altro canale prima che tu possa vedere l’errore; un errore upstream temporaneo diventa un successo più lento invece del tuo 503. Le richieste fallite non vengono mai addebitate e, poiché una chiave copre Gemini, Claude e GPT, il fallback tra provider nel passaggio 3 consiste nel cambiare la stringa del modello, non nel creare una seconda integrazione. Stai valutando un modello di fallback? Le tariffe per token dell’intera famiglia Gemini, accanto ai prezzi di listino di Google, sono nella pagina dei prezzi dell’API Gemini.
Domande frequenti
Mi vengono addebitate le richieste che restituiscono 503?
No: la richiesta viene rifiutata prima dell’inferenza, quindi Google non la addebita; anche su Kunavo le richieste fallite non vengono mai addebitate. Il costo di un 503 è latenza e retry, non token.
Quanto durano i sovraccarichi di Gemini?
Di solito da pochi secondi a qualche minuto; i picchi al lancio di un nuovo modello possono durare più a lungo. Per questo la politica sensata consiste in alcuni retry con backoff, seguiti da un modello di fallback, non in un ciclo di retry senza limiti.
Passare al livello a pagamento elimina i 503?
No. I livelli a pagamento aumentano le quote (la famiglia 429), ma 503 UNAVAILABLE indica capacità condivisa di distribuzione: il traffico gratuito e quello a pagamento lo ricevono entrambi quando un pool è saturo. Il rimedio sono i fallback, non la fatturazione.
Guide correlate
- Prezzi dell'API Google Gemini settembre 2026 — listino ufficiale e tariffe per token 2026
- API Gemini 3 — prezzi, disponibilità e come chiamare Gemini oggi
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.