Les erreurs de l'API Gemini semblent nombreuses, mais elles se rangent en pratique en quatre catégories : identité incorrecte, adresse incorrecte, quota insuffisant, réseau inaccessible. Les problèmes réellement causés par le modèle lui-même sont plus rares.
Cet article les détaille par code d'erreur et propose un ordre de diagnostic partant d'une requête minimale. En cas de problème, conservez d'abord le JSON d'erreur complet, puis vérifiez dans l'ordre : ne modifiez pas en même temps la clé, l'adresse et le modèle.
Remarque : Google et Gemini sont des marques de leurs détenteurs. Cet article décrit les formes d'interface courantes d'octobre 2026 ; la version d'interface, les quotas et les politiques régionales font foi dans la documentation du fournisseur et sur la page Tarifs des modèles.
1. Apprendre à lire le corps d'erreur
Les erreurs des API Google renvoient généralement du JSON, avec trois champs clés :
{
"error": {
"code": 429,
"message": "Quota exceeded for quota metric ...",
"status": "RESOURCE_EXHAUSTED"
}
}
code est le code HTTP, status le type d'erreur lisible par machine, message contient souvent la cause précise, et details peut préciser l'identifiant de quota et le délai de nouvelle tentative conseillé. Il faut lire les trois : voir seulement « 429 » masque la différence entre une limitation à la minute et un quota journalier épuisé.
| Code | status courant |
Direction générale |
|---|---|---|
| 401 | UNAUTHENTICATED | Clé absente, invalide ou mal placée |
| 403 | PERMISSION_DENIED | Projet non activé, permission ou région limitée |
| 404 | NOT_FOUND | Nom de modèle, chemin ou version incorrect |
| 429 | RESOURCE_EXHAUSTED | Débit, concurrence ou quota dépassé |
| 400 | INVALID_ARGUMENT / FAILED_PRECONDITION | Paramètre incorrect, région non prise en charge, précondition manquante |
| 500/503 | INTERNAL / UNAVAILABLE | Panne amont temporaire, généralement réessayable après backoff |
2. 401 : clé invalide ou mauvais mode d'authentification
Un 401 signifie que le serveur ne reconnaît pas votre identité. Causes fréquentes :
- La requête ne contient aucune clé, ou la variable d'environnement est vide.
- L'interface native utilise
Authorizationau lieu dex-goog-api-key. - L'interface compatible OpenAI utilise
x-goog-api-keyau lieu deAuthorization: Bearer. - La clé contient des espaces, des sauts de ligne ou des guillemets collés par erreur.
- La clé a été supprimée, renouvelée, ou son projet désactivé.
- Une clé de passerelle est envoyée à l'adresse Google, ou l'inverse.
- La clé a des restrictions d'API qui interdisent l'appel à Gemini.
Validez d'abord avec une requête minimale :
export GEMINI_API_KEY="votre-clé"
# Interface Gemini native
curl "https://generativelanguage.googleapis.com/v1beta/models/<ID-modèle>:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"contents":[{"parts":[{"text":"Réponds seulement OK"}]}]}'
# Interface compatible OpenAI
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Authorization: Bearer $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"<ID-modèle>","messages":[{"role":"user","content":"Réponds seulement OK"}]}'
Les deux commandes correspondent à deux systèmes d'authentification. Celle qui fonctionne indique à quel ensemble appartiennent votre clé et votre adresse ; un 401 en cas de mélange ne signifie pas que la clé est cassée, mais que la combinaison est mauvaise.
3. 404 : nom de modèle, chemin ou version incorrect
Un 404 ne signifie pas nécessairement que « le modèle n'existe pas ». Cas fréquents :
- L'identifiant du modèle est mal orthographié, ou vous utilisez le nom affiché dans la console au lieu de l'identifiant API.
- Le modèle n'appartient pas à la version d'API courante, par exemple un modèle ouvert uniquement en version récente appelé sur un ancien chemin.
- L'URL de base contient un
/v1ou/v1betaen trop ou manquant, et la concaténation produit une adresse inexistante. - Une barre oblique finale double le chemin ajouté par le client.
- Via une passerelle, le modèle n'est pas ouvert dans le groupe ou l'offre courante.
- Une interface de chat est utilisée pour appeler la génération d'images ou une interface spécialisée.
Commencez par lister les modèles disponibles pour la clé :
curl "https://generativelanguage.googleapis.com/v1beta/models" \
-H "x-goog-api-key: $GEMINI_API_KEY"
Si le modèle cible figure dans la liste, vérifiez le chemin de la requête ; sinon, réglez d'abord l'ouverture du modèle ou les permissions. Via une passerelle, utilisez l'identifiant et l'URL de base indiqués par sa documentation, sans reprendre directement le nom donné par le fournisseur.
4. 429 : distinguer limitation et quota épuisé
Le 429 est le plus souvent mal interprété. Il couvre au moins trois situations :
| Type | Signe typique | Direction |
|---|---|---|
| Limitation à la minute | Concurrence élevée sur peu de temps, erreurs concentrées en quelques secondes | Réduire la concurrence, backoff |
| Quota journalier épuisé | Plafond atteint dans la journée, échecs persistants | Attendre la réinitialisation, augmenter le quota ou changer de solution |
| Quota de projet | Plusieurs services partagent un projet et se disputent le quota | Séparer projets et clés, quotas dédiés |
Le champ details du corps d'erreur indique généralement l'identifiant de quota et le délai conseillé. Ne renvoyez pas immédiatement sur un 429 : une tempête de tentatives aggrave la situation. Installez d'abord la dépendance : pip install requests. Exemple de logique de backoff :
import random
import time
import requests
def generate(prompt: str, retries: int = 4):
url = "https://generativelanguage.googleapis.com/v1beta/models/<ID-modèle>:generateContent"
headers = {
"x-goog-api-key": "votre-clé",
"Content-Type": "application/json",
}
for attempt in range(retries):
resp = requests.post(
url,
headers=headers,
json={"contents": [{"parts": [{"text": prompt}]}]},
timeout=60,
)
if resp.status_code == 200:
return resp.json()
if resp.status_code not in (429, 500, 503):
resp.raise_for_status()
wait = min(2 ** attempt, 30) + random.random()
time.sleep(wait)
raise RuntimeError("Tentatives épuisées")
Les nouvelles tentatives ne règlent que la congestion temporaire, pas l'épuisement du quota. En production, ajoutez timeouts, disjoncteur et modèle de secours ; sinon un seul 429 peut faire tomber toute la chaîne.
5. Restrictions régionales : pourquoi l'accès direct depuis la Chine échoue
L'API Gemini n'est disponible que dans certains pays et régions. Lorsque la sortie de la requête se trouve dans une région non prise en charge, trois symptômes sont fréquents :
- Timeout de connexion ou échec de la poignée de main TLS, souvent un chemin réseau bloqué.
- Réponse
400 FAILED_PRECONDITIONavec un message du type « location is not supported ». - Réponse
403 PERMISSION_DENIED, liée au projet, à la facturation ou aux permissions régionales.
Deux notions sont souvent confondues : la région d'inscription du compte et la région de sortie de la requête. Même si le compte est valide, un serveur déployé dans une région non prise en charge peut être refusé ; inversement, un proxy local qui ouvre une page web ne signifie pas que la requête API emprunte le même chemin.
Ordre de traitement recommandé :
- Identifiez si la requête part d'une machine locale, d'un conteneur ou d'un serveur, et trouvez l'IP de sortie réelle.
- Vérifiez si la région de sortie figure dans la liste prise en charge par le fournisseur.
- Contrôlez la région choisie pour le serveur cloud et changez-la si nécessaire.
- Si l'activité est principalement en Chine, évaluez une passerelle conforme pour traiter réseau et facturation au même endroit.
- Ne considérez pas le « changement d'IP » comme l'unique solution : vérifiez d'abord les conditions de service et la réglementation locale.
6. Autres erreurs fréquentes
| Symptôme | Cause fréquente | Traitement |
|---|---|---|
| 400 INVALID_ARGUMENT | Structure JSON incorrecte, ordre des rôles, format d'image non pris en charge | Ajouter les champs un par un sur une requête minimale |
| 400 FAILED_PRECONDITION | Région non prise en charge, facturation inactive, précondition manquante | Vérifier région, facturation et état du projet |
| 403 PERMISSION_DENIED | API non activée, restriction de clé, permissions de projet insuffisantes | Activer dans la console et vérifier les permissions |
| 500 INTERNAL | Erreur interne amont | Backoff, conserver l'identifiant de requête |
| 503 UNAVAILABLE | Surcharge ou maintenance amont | Backoff, basculer sur un modèle de secours |
| Réponse sans contenu | Filtrage de sécurité, sortie tronquée | Lire blockReason et finishReason |
| Sortie interrompue | Nombre maximal de tokens atteint | Augmenter la limite ou raccourcir l'entrée |
Une « réponse sans contenu » est souvent prise pour une panne, alors qu'il s'agit d'un filtre de sécurité ou d'une limite de longueur. Lisez promptFeedback.blockReason, finishReason et usageMetadata avant de décider s'il faut modifier le prompt ou les paramètres.
7. Ordre de diagnostic recommandé
- Conservez le JSON d'erreur complet, l'heure, l'identifiant de modèle et l'identifiant de requête.
- Envoyez une requête minimale avec curl pour écarter le client et le SDK.
- Vérifiez trois éléments : URL de base, en-tête d'authentification, identifiant de modèle.
- Essayez un modèle connu comme disponible pour distinguer modèle et chaîne d'appel.
- Consultez quotas, facturation et état du projet pour distinguer 429 et 403.
- Confirmez la région de sortie et le chemin réseau.
- Vérifiez enfin la configuration du client, le proxy et la logique de nouvelles tentatives dans le code.
Ne changez qu'une variable à la fois. Sinon, même après rétablissement, vous ne saurez pas quelle étape a corrigé le problème et vous retomberez dessus.
8. Questions fréquentes
Quelle différence entre 401 et 403 ?
Un 401 signifie « identité non validée » : vérifiez d'abord la clé, l'en-tête d'authentification et la cohérence de l'adresse. Un 403 signifie « identité validée mais permission refusée » : vérifiez l'activation de l'API, les permissions du projet, les restrictions de clé et la politique régionale.
Suffit-il d'attendre quelques minutes après un 429 ?
Cela dépend du type de quota. Une limitation à la minute se rétablit généralement après backoff ; un quota journalier épuisé exige une réinitialisation ou une augmentation. Lisez l'identifiant de quota et le conseil de nouvelle tentative dans le corps d'erreur, sans renvoyer à l'aveugle.
Changer d'IP suffit-il à contourner une restriction régionale ?
Pas nécessairement. Cela dépend de la région de sortie réelle, de l'état du compte et des conditions de service. En entreprise, il est plus sûr de déployer dans une région prise en charge ou de passer par une passerelle conforme.
L'adresse du fournisseur fonctionne mais la passerelle renvoie 404 : qui est en cause ?
Vérifiez d'abord l'URL de base et l'identifiant de modèle de la passerelle. Le nommage, les chemins et le périmètre disponible peuvent différer : ne reprenez pas directement la requête du fournisseur. Remplacez chaque élément à partir de l'exemple minimal de la documentation de la passerelle.
Comment éviter que les nouvelles tentatives gonflent le coût ?
Fixez un nombre maximal de tentatives, un backoff exponentiel et des timeouts ; traitez les 429 séparément ; dédupliquez les requêtes non idempotentes ; configurez un plafond budgétaire et des alertes côté passerelle.
Pour aller plus loin
La clé du diagnostic Gemini est de distinguer d'abord les quatre familles « authentification, chemin, quota, réseau », puis de valider chaque point avec une requête minimale. Si vous avez besoin d'une entrée unifiée et de réduire l'incertitude de l'accès direct depuis la Chine, inscrivez-vous sur ZSQH AI Gateway ; les modèles, quotas et tarifs font foi sur la page Tarifs des modèles.
Articles liés :
