Gemini 503 « The model is overloaded » (UNAVAILABLE) — nouvelles tentatives efficaces et moment où s’arrêter

« The model is overloaded » est la seule erreur Gemini qui ne vous concerne pas : le pool de serveurs de ce modèle n’a momentanément plus de capacité. Aucun paramètre de votre projet ne peut l’empêcher ; vous contrôlez en revanche la manière de gérer l’incident et le modèle de secours utilisé s’il persiste.

L’erreur

response (HTTP 503)

{
  "error": {
    "code": 503,
    "message": "The model is overloaded. Please try again later.",
    "status": "UNAVAILABLE"
  }
}

Causes et solutions en bref

Cause	Solution
Pic de demande sur le pool de serveurs de ce modèle	Temporisation exponentielle avec jitter ; le pic disparaît généralement en quelques secondes à quelques minutes.
Variantes de modèles en préversion / expérimentales	Les versions -exp et preview utilisent de petits pools et sont les premières à être surchargées. Épinglez l’alias stable en production.
Requêtes lourdes aux heures de pointe	Les contextes volumineux et les plafonds de sortie élevés sont plus susceptibles d’être supprimés sous forte charge : réduisez ce qui est inutile et diffusez la réponse en streaming.

Confirmez qu’il s’agit de 503 UNAVAILABLE, et non de 429

429 RESOURCE_EXHAUSTED concerne votre quota ; 503 UNAVAILABLE concerne la capacité de Google. Cette distinction détermine toute la suite : les erreurs de quota nécessitent des modifications de facturation ou de limites, tandis que les erreurs de capacité nécessitent des nouvelles tentatives et des solutions de secours. Ne cherchez pas dans les paramètres de votre projet pour une erreur 503 : il n’y a rien à y trouver.

Réessayez avec une temporisation — mais avec un budget

Par définition, 503 peut faire l’objet d’une nouvelle tentative. Utilisez la même temporisation exponentielle avec jitter que pour toute erreur 429 (l’extrait de notre guide Claude 429 fonctionne sans modification : il réessaie déjà les statuts de classe 500), mais plafonnez l’attente totale à ce que votre appelant peut absorber ; une surcharge qui persiste après environ 5 tentatives sur une minute ne disparaîtra probablement pas rapidement.

Lorsque les tentatives sont épuisées : changez de modèle, pas de boucle

Préparez une chaîne de secours avant d’en avoir besoin : l’alias stable si vous utilisiez une version preview, gemini-2-5-flash si 2.5 Pro est en difficulté (ou inversement), ou un autre fournisseur pour la requête qui ne doit pas échouer. Les solutions de secours transforment une panne en dégradation de qualité.

Si vous appelez via Kunavo

C’est pourquoi Kunavo réessaie à l’intérieur de la requête : lorsqu’un modèle dispose de plusieurs canaux amont configurés, une tentative échouée bascule vers l’autre canal avant même que vous ne voyiez l’erreur ; une défaillance amont transitoire devient une réussite plus lente au lieu de votre 503. Les requêtes échouées ne sont jamais facturées et, comme une seule clé couvre Gemini, Claude et GPT, le basculement inter-fournisseurs de l’étape 3 consiste à modifier le nom du modèle plutôt qu’à intégrer un second service. Vous évaluez un modèle de secours ? Les tarifs par token pour toute la famille Gemini, à côté des tarifs catalogue de Google, figurent sur la liste des prix de l’API Gemini.

Questions fréquentes

Les requêtes qui renvoient 503 sont-elles facturées ?

Non : la requête est rejetée avant l’inférence, donc Google ne la facture pas, et Kunavo ne facture pas non plus les requêtes échouées. Le coût d’un 503 est la latence et les nouvelles tentatives, pas les tokens.

Combien de temps durent les surcharges de Gemini ?

Généralement de quelques secondes à quelques minutes ; les pics du jour de lancement d’un nouveau modèle peuvent durer plus longtemps. C’est pourquoi la politique raisonnable consiste à effectuer quelques nouvelles tentatives avec temporisation, puis à utiliser un modèle de secours — et non une boucle de tentatives illimitée.

Le passage à une offre payante empêche-t-il les 503 ?

Non. Les offres payantes augmentent vos quotas (la famille 429), mais 503 UNAVAILABLE correspond à une capacité de service partagée : le trafic gratuit comme le trafic payant y est confronté lorsqu’un pool est saturé. Les solutions de secours sont la mitigation, pas la facturation.

Guides associés

La sémantique détaillée des erreurs est disponible dans référence des erreurs ; obtenir une clé prend une minute via inscription et la guide d’authentification.