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 plus récente de l'API avec un ancien point de terminaison 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 disponible 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 une clé API incorrecte ou 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 les 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 si tous les paramètres de votre requête sont valides pour votre version de l'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 un peu, puis réessayez. 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 prématurément la connexion (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. Le contexte de votre entrée est trop long. Consultez la page d'état de l'API Gemini pour connaître les incidents en cours. Réduisez le contexte de votre 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 un peu, puis réessayer d'envoyer 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 un peu, puis réessayer d'envoyer 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 la 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 les détails de 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