Erreurs d'API

Cette page fournit une référence pour les codes d'erreur de backend renvoyés par l'API GenerateContent, décrit le format de réponse d'erreur gRPC et fournit des étapes de dépannage.

Codes d'erreur HTTP

Le tableau suivant répertorie les codes d'erreur de backend courants, explique leurs causes et fournit des solutions recommandées :

Code HTTP État Description Exemple Solution
400 INVALID_ARGUMENT Le corps de la requête est mal formé. Votre requête contient une faute de frappe ou un champ obligatoire manquant. Consultez la documentation de référence de l'API pour connaître le format des requêtes, des exemples et les versions compatibles. L'utilisation de fonctionnalités d'une version d'API plus récente avec un point de terminaison plus ancien peut entraîner des erreurs.
400 FAILED_PRECONDITION Le niveau sans frais de l'API Gemini n'est pas disponible dans votre pays. Veuillez activer la facturation dans votre projet dans Google AI Studio. Vous effectuez une requête dans une région où le niveau sans frais n'est pas compatible et vous n'avez pas activé la facturation dans votre projet dans Google AI Studio. Pour utiliser l'API Gemini, vous devez configurer un forfait payant à l'aide de Google AI Studio.
403 PERMISSION_DENIED Votre clé API ne dispose pas des autorisations requises. Vous utilisez la mauvaise clé API. Vous essayez d'utiliser un modèle ajusté sans passer par une authentification appropriée. Vérifiez que votre clé API est définie et qu'elle dispose des droits d'accès appropriés. Assurez-vous également de passer par une authentification appropriée pour utiliser des modèles ajustés.
404 NOT_FOUND La ressource demandée est introuvable. Un fichier image, audio ou vidéo référencé dans votre requête est introuvable. Vérifiez que tous les paramètres de votre requête sont valides pour votre version d'API.
429 RESOURCE_EXHAUSTED Vous avez dépassé l'une des limites de débit de l'API (RPM, TPM, RPD, dépenses, etc.). Vous envoyez trop de requêtes, utilisez trop de jetons ou dépassez les limites basées sur les dépenses pour l'historique de facturation et le niveau de votre compte. Vérifiez que vous respectez les limites de débit du modèle. Patientez quelques instants, puis relancez la requête. Réduisez le débit ou la taille de vos requêtes. Demandez une augmentation de la limite de débit si nécessaire.
499 ANNULÉ L'opération a été annulée, généralement par l'appelant. Le client a fermé la connexion avant que l'API n'ait pu terminer de répondre. Vérifiez si votre client ou votre infrastructure réseau ferme la connexion prématurément (par exemple, en raison d'un délai avant expiration côté client).
500 INTERNE Une erreur inattendue s'est produite du côté de Google. Votre contexte d'entrée est trop long. Consultez la page d'état de l'API Gemini pour connaître les incidents en cours. Réduisez votre contexte d'entrée ou passez temporairement à un autre modèle (par exemple, de Gemini 2.5 Pro à Gemini 2.5 Flash) et voyez si cela fonctionne. Vous pouvez également patienter quelques instants, puis relancer votre requête. Si le problème persiste après plusieurs tentatives, veuillez le signaler à l'aide du bouton Envoyer des commentaires dans Google AI Studio.
503 UNAVAILABLE Le service est peut-être temporairement surchargé ou en panne. Le service manque temporairement de capacité. Consultez la page d'état de l'API Gemini pour connaître les incidents en cours. Passez temporairement à un autre modèle (par exemple, de Gemini 2.5 Pro à Gemini 2.5 Flash) et voyez si cela fonctionne. Vous pouvez également patienter quelques instants, puis relancer votre requête. Si le problème persiste après plusieurs tentatives, veuillez le signaler à l'aide du bouton Envoyer des commentaires dans Google AI Studio.
504 DEADLINE_EXCEEDED Le service ne parvient pas à terminer le traitement dans le délai imparti. Votre prompt (ou contexte) est trop volumineux pour être traité à temps. Définissez un délai avant expiration plus long dans votre requête client pour éviter cette erreur.

Format de réponse d'erreur

Lorsqu'une requête GenerateContent échoue, l'API définit le code d'état HTTP (par exemple, 400 Bad Request, 403 Forbidden ou 429 Too Many Requests) et renvoie un corps de réponse JSON contenant des informations sur l'état gRPC :

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
Champ Type Description
code entier Code d'état HTTP.
message chaîne Description de l'erreur compréhensible par l'utilisateur.
status chaîne Code d'état gRPC au format SCREAMING_CASE.
details tableau Contexte d'erreur supplémentaire, tel que ErrorInfo ou LocalizedMessage.

Étape suivante