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
Pour obtenir une référence complète de tous les codes d'erreur, y compris les codes d'état HTTP, les codes de génération bloquée et les codes d'erreur de contenu, consultez la page Erreurs d'API.
Stratégie de nouvelle tentative
Si vous recevez une erreur indiquant que vous devez réessayer votre requête (par exemple, 429 RESOURCE_EXHAUSTED ou 503 UNAVAILABLE), nous vous recommandons d'implémenter une stratégie d'intervalle exponentiel entre les tentatives. Cela signifie que vous attendez un court instant avant la première tentative, puis que vous augmentez progressivement le temps d'attente entre les tentatives suivantes.
Les SDK client officiels pour l'API Gemini, tels que le SDK Python, incluent par défaut une logique de nouvelle tentative automatique avec intervalle exponentiel entre les tentatives pour gérer les erreurs temporaires telles que les délais d'attente, les problèmes de réseau et les limites de débit (429 et 5xx codes d'état). Par exemple, le SDK Python retente automatiquement les erreurs temporaires jusqu'à quatre fois avec un délai initial d'environ une seconde et un délai maximal de 60 secondes.
Si vous effectuez des requêtes d'API REST directes ou si vous personnalisez votre logique de nouvelle tentative, suivez ces bonnes pratiques pour augmenter les chances de réussite d'une requête et éviter de surcharger le service :
- Utilisez un intervalle exponentiel entre les tentatives : attendez un court instant avant la première tentative (par exemple, une seconde), puis augmentez le délai de manière exponentielle (par exemple, 2 s, 4 s, 8 s).
- Ajoutez une gigue : ajoutez une "gigue" aléatoire au délai pour éviter que tous les clients ne retentent exactement au même moment.
- Retentez en cas d'erreurs spécifiques : ne retentez que les erreurs temporaires (comme
429,408ou5xx). Ne retentez pas les erreurs client (comme400ou403), car elles indiquent des problèmes tels que des clés API non valides ou une syntaxe incorrecte. - Définissez un nombre maximal de tentatives : définissez un nombre maximal de tentatives pour éviter les boucles infinies.
Vérifiez que vos appels d'API ne contiennent pas d'erreurs de paramètres de modèle
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 qui prend en charge 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érifiez que 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 de réflexion
Une latence ou une utilisation de jetons plus élevées se produisent souvent, car la réflexion est activée par défaut pour les modèles Gemini 3.x. Les modèles Gemini 2.5 obsolètes utilisent également la réflexion par défaut.
Les modèles de réflexion génèrent des jetons de raisonnement interne pour améliorer la qualité. Ce processus de raisonnement augmente à la fois la latence de réponse et la consommation totale de jetons.
Si vous privilégiez une latence plus faible ou si vous devez réduire les coûts, vous pouvez réduire le niveau de réflexion ou désactiver la réflexion.
Pour obtenir des informations sur la configuration et des exemples de code, consultez le guide de réflexion.
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 (>= 0,8) s'est avérée plus efficace. 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 d'échappement ou Unicode telles que
\u ou \t, cela peut entraîner des sauts de ligne répétés.
|
|
| Texte répété dans la 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 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 comme ayant é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 vérifier 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
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 commencer à émettre des clés API lorsque vous demanderez une nouvelle clé à l'aide de Google AI Studio. Par défaut, elles 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.
- Nous allons bloquer par défaut les clés API divulguées et utilisées avec l'API Gemini, ce qui permettra 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 mises à jour.
Signaler un bug
Si vous avez des questions, participez à la discussion sur le forum des développeurs Google AI.