Ce guide vous aidera à diagnostiquer et à résoudre les problèmes courants qui surviennent lorsque vous appelez l'API Gemini. Vous pouvez rencontrer des problèmes avec le service de backend de l'API Gemini ou avec les SDK client. Nos SDK client sont Open Source dans les dépôts suivants :
Si vous rencontrez des problèmes avec la clé API, vérifiez que vous l'avez configurée correctement conformément au guide de configuration de la clé API.
Codes d'erreur du service de backend de l'API Gemini
Le tableau suivant répertorie les codes d'erreur de backend courants que vous pouvez rencontrer, ainsi que des explications sur leurs causes et des étapes de dépannage :
| 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 l'authentification appropriée. | Vérifiez que votre clé API est définie et qu'elle dispose des droits d'accès appropriés. Veillez également à passer par l'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 que tous les paramètres de votre requête sont valides pour votre version d'API. |
| 429 | RESOURCE_EXHAUSTED | Vous avez dépassé la limite de débit. | Vous envoyez trop de requêtes par minute avec le niveau sans frais de l'API Gemini. | Vérifiez que vous respectez la limite de débit du modèle. Demandez une augmentation de quota si nécessaire. |
| 500 | INTERNE | Une erreur inattendue s'est produite du côté de Google. | Votre contexte d'entrée est trop long. | 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 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é. | 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 d'expiration plus long dans votre requête client pour éviter cette erreur. |
Vérifier les erreurs de paramètres de modèle dans vos appels d'API
Vérifiez que les paramètres de votre modèle se situent dans les valeurs suivantes :
| Paramètre de modèle | Valeurs (plage) |
| Nombre de candidats | 1-8 (entier) |
| Température | 0.0-1.0 |
| Nombre maximal de jetons de sortie | Utilisez la page des modèles pour déterminer le nombre maximal de jetons pour le modèle que vous utilisez. |
| TopP | 0.0-1.0 |
En plus de vérifier les valeurs des paramètres, assurez-vous d'utiliser la bonne
version d'API (par exemple, /v1 ou /v1beta) et le
modèle compatible avec les fonctionnalités dont vous avez besoin. Par exemple, si une fonctionnalité est en version bêta, elle ne sera disponible que dans la version d'API /v1beta.
Vérifier si vous disposez du bon modèle
Vérifiez que vous utilisez un modèle compatible listé sur notre page des modèles.
Latence ou utilisation de jetons plus élevées avec les modèles 2.5
Si vous constatez une latence ou une utilisation de jetons plus élevées avec les modèles 2.5 Flash et Pro, cela peut être dû au fait que la réflexion est activée par défaut afin d'améliorer la qualité. Si vous privilégiez la vitesse ou devez réduire les coûts, vous pouvez ajuster ou désactiver la réflexion.
Consultez la page sur la réflexion pour obtenir des conseils et un exemple de code.
Problèmes de sécurité
Si vous voyez qu'un prompt a été bloqué en raison d'un paramètre de sécurité dans votre appel d'API, examinez le prompt par rapport aux filtres que vous avez définis dans l'appel d'API.
Si vous voyez BlockedReason.OTHER, la requête ou la réponse peut enfreindre les conditions
d'utilisation ou ne pas être compatible.
Problème de récitation
Si vous voyez que le modèle cesse de générer une sortie en raison de la récitation, cela signifie que la sortie du modèle peut ressembler à certaines données. Pour résoudre ce problème, essayez de rendre le prompt / contexte aussi unique que possible et utilisez une température plus élevée.
Problème de jetons répétitifs
Si vous voyez des jetons de sortie répétés, essayez les suggestions suivantes pour les réduire ou les éliminer.
| Description | Cause | Solution suggérée |
|---|---|---|
| Tirets répétés dans les tableaux Markdown | Cela peut se produire lorsque le contenu du tableau est long, car le modèle tente de créer un tableau Markdown visuellement aligné. Toutefois, l'alignement en Markdown n'est pas nécessaire pour un rendu correct. |
Ajoutez des instructions dans votre prompt pour fournir au modèle des consignes spécifiques pour générer des tableaux Markdown. Fournissez des exemples qui suivent ces consignes. Vous pouvez également essayer d'ajuster la température. Pour générer du code ou une sortie très structurée comme des tableaux Markdown, une température élevée s'est avérée plus efficace (>= 0.8). Voici un exemple d'ensemble de consignes que vous pouvez ajouter à votre prompt pour éviter ce problème :
# Markdown Table Format
* Separator line: Markdown tables must include a separator line below
the header row. The separator line must use only 3 hyphens per
column, for example: |---|---|---|. Using more hypens like
----, -----, ------ can result in errors. Always
use |:---|, |---:|, or |---| in these separator strings.
For example:
| Date | Description | Attendees |
|---|---|---|
| 2024-10-26 | Annual Conference | 500 |
| 2025-01-15 | Q1 Planning Session | 25 |
* Alignment: Do not align columns. Always use |---|.
For three columns, use |---|---|---| as the separator line.
For four columns use |---|---|---|---| and so on.
* Conciseness: Keep cell content brief and to the point.
* Never pad column headers or other cells with lots of spaces to
match with width of other content. Only a single space on each side
is needed. For example, always do "| column name |" instead of
"| column name |". Extra spaces are wasteful.
A markdown renderer will automatically take care displaying
the content in a visually appealing form.
|
| Jetons répétés dans les tableaux Markdown | Comme pour les tirets répétés, cela se produit lorsque le modèle tente de aligner visuellement le contenu du tableau. L'alignement en Markdown n'est pas nécessaire pour un rendu correct. |
|
Sauts de ligne répétés (\n) dans la sortie structurée
|
Lorsque l'entrée du modèle contient des séquences Unicode ou d'échappement telles que
\u ou \t, cela peut entraîner des sauts de ligne répétés.
|
|
| Texte répété lors de l'utilisation d'une sortie structurée | Lorsque la sortie du modèle présente un ordre différent pour les champs par rapport au schéma structuré défini, cela peut entraîner la répétition du texte. |
|
| Appel d'outil répétitif | Cela peut se produire si le modèle perd le contexte des pensées précédentes et/ou appelle un point de terminaison non disponible auquel il est forcé d'accéder. |
Demandez au modèle de conserver l'état dans son processus de réflexion.
Ajoutez ceci à la fin de vos instructions système :
When thinking silently: ALWAYS start the thought with a brief
(one sentence) recap of the current progress on the task. In
particular, consider whether the task is already done.
|
| Texte répétitif qui ne fait pas partie de la sortie structurée | Cela peut se produire si le modèle est bloqué sur une requête qu'il ne peut pas résoudre. |
|
Clés API bloquées ou non fonctionnelles
Cette section explique comment vérifier si votre clé API Gemini est bloquée et comment résoudre ce problème.
Comprendre pourquoi les clés sont bloquées
Nous avons identifié une faille de sécurité qui a pu exposer publiquement certaines clés API. Pour protéger vos données et empêcher tout accès non autorisé, nous avons bloqué de manière proactive l'accès à l'API Gemini pour ces clés connues comme ayant été divulguées.
Vérifier si vos clés sont concernées
Si votre clé est connue pour avoir été divulguée, vous ne pouvez plus l'utiliser avec l'API Gemini. Vous pouvez utiliser Google AI Studio pour voir si l'une de vos clés API est bloquée pour l'appel de l'API Gemini et générer de nouvelles clés. L'erreur suivante peut également s'afficher lorsque vous tentez d'utiliser ces clés :
Your API key was reported as leaked. Please use another API key.
Action pour les clés API bloquées
Vous devez générer de nouvelles clés API pour vos intégrations d'API Gemini à l'aide de Google AI Studio. Nous vous recommandons vivement de revoir vos pratiques de gestion des clés API pour vous assurer que vos nouvelles clés sont sécurisées et ne sont pas exposées publiquement.
Frais inattendus dus à une faille de sécurité
Envoyez une demande d'assistance concernant la facturation. Notre équipe de facturation travaille sur ce problème et nous vous communiquerons les mises à jour dès que possible.
Mesures de sécurité de Google pour les clés divulguées
Comment Google va-t-il m'aider à sécuriser mon compte contre les dépassements de coûts et les utilisations abusives si mes clés API sont divulguées ?
- Nous allons émettre des clés API lorsque vous demanderez une nouvelle clé à l'aide de Google AI Studio. Par défaut, ces clés seront limitées à Google AI Studio et n'accepteront pas les clés d'autres services. Cela permettra d'éviter toute utilisation croisée involontaire des clés.
- Par défaut, nous bloquons les clés API qui sont divulguées et utilisées avec l'API Gemini, ce qui permet d'éviter les utilisations abusives des coûts et des données de votre application.
- Vous pourrez consulter l'état de vos clés API dans Google AI Studio. Nous vous informerons de manière proactive lorsque nous identifierons que vos clés API ont été divulguées afin que vous puissiez prendre des mesures immédiates.
Améliorer la sortie du modèle
Pour obtenir des sorties de modèle de meilleure qualité, essayez d'écrire des prompts plus structurés. La page du guide d'ingénierie des prompts présente des concepts, des stratégies et des bonnes pratiques de base pour vous aider à démarrer.
Comprendre les limites de jetons
Consultez notre guide sur les jetons pour mieux comprendre comment les compter et connaître leurs limites.
Problèmes connus
- L'API n'est compatible qu'avec un certain nombre de langues. L'envoi de prompts dans des langues non compatibles peut générer des réponses inattendues, voire bloquées. Consultez les langues disponibles pour obtenir des informations à jour.
Signaler un bug
Si vous avez des questions, participez à la discussion sur le forum des développeurs Google AI.