Erreurs d’API d’IA : 401, 429, 5xx et délais d’attente dépassés
Distinguez authentification, quotas, limites de requêtes et erreurs transitoires pour les API OpenAI, Claude et Gemini. Utilisez les détails d’erreur avant de décider de réessayer.
Réponse rapide
Une erreur d’API ne prouve pas à elle seule une panne du fournisseur. Consultez le corps de l’erreur et l’identifiant de requête du fournisseur, puis vérifiez le composant d’état correspondant. Les problèmes d’authentification et de facturation nécessitent des changements de configuration ; les erreurs transitoires peuvent justifier un nombre limité de nouvelles tentatives.
Commencez par la catégorie d’erreur
Utilisez ce tableau pour choisir une première vérification. Les significations et remèdes exacts dépendent du fournisseur, du point de terminaison et du corps d’erreur.
| Ce que vous voyez | Première vérification | Ce que cela ne prouve pas |
|---|---|---|
| 400 / 404 / 413 | Format de requête, point de terminaison, ressource et taille ; consultez l’erreur fournisseur | Une panne générale du service |
| 401 / 403 | Identifiants, autorisations d’accès et restrictions propres au fournisseur | Que tous les utilisateurs sont bloqués |
| 429 | En-têtes de limites de requêtes, quotas, crédits et plafonds de dépenses | Que réessayer immédiatement fonctionnera |
| 500 / 503 / 529 | Détails d’erreur fournisseur et composant officiel pertinent | Un incident global confirmé |
| Délai dépassé / erreur de connexion | Délai du client, DNS, TLS, proxy et durée de requête | Quel côté a causé l’échec |
OpenAI : un 429 peut indiquer différentes limites
Examinez error.code, pas seulement HTTP 429. OpenAI distingue les limites de fréquence des crédits épuisés et des limites d’organisation ou de projet. Les problèmes de facturation et de quota ne se résolvent pas par de nouvelles tentatives. Pour les limites transitoires ou la surcharge, respectez Retry-After lorsqu’il est présent et bornez les tentatives.
Utilisez l’entrée OpenAI API pour les composants API. L’entrée de l’application ChatGPT ne confirme pas le résultat d’une requête API ou la santé d’un modèle GPT précis.
Claude : surcharge et plafonds de dépenses sont distincts
Claude définit 529 comme une surcharge, 401 comme un échec d’authentification et 403 comme un échec d’autorisation. Un 429 peut refléter une limite de requêtes ou un plafond de dépenses. Un 429 lié au plafond de dépenses du niveau d’utilisation n’a pas d’en-tête Retry-After et continue d’échouer jusqu’au rétablissement de l’accès. Consultez l’erreur complète avant de choisir une politique de nouvelles tentatives.
Pour les réponses en flux, Claude indique qu’une erreur peut se produire après HTTP 200. Vérifiez la fin du flux et les événements d’erreur ; recevoir uniquement les en-têtes ne prouve pas une génération réussie.
Gemini : vérifiez le point de terminaison pour développeurs
Google recommande un recul exponentiel borné avec variation aléatoire pour les erreurs transitoires. Vérifiez aussi la version de l’API, le modèle et les paramètres pris en charge. Consultez le rapport propre à l’API pour développeurs ; le flux de l’application Gemini ne couvre pas les requêtes Gemini API ou AI Studio.
Fixez un budget de nouvelles tentatives
En tant que choix de conception de l’application, fixez un nombre maximal de tentatives et un budget de temps total. Tenez compte des tentatives déjà effectuées par votre SDK. Utilisez un délai avec recul exponentiel et variation aléatoire pour les erreurs que le fournisseur identifie comme transitoires, et respectez les en-têtes de nouvelle tentative applicables.
Avant de rejouer une requête interrompue, vérifiez si elle a déjà pu produire une sortie, une facturation ou une action en aval. Réessayer une requête de modèle et répéter une action d’outil d’un agent sont des décisions distinctes. Conservez les identifiants de requête pour le diagnostic et arrêtez les tentatives automatiques lorsque le budget autorisé est épuisé.
Diagnostiquer une réponse précise
Utilisez un guide dédié à l’erreur renvoyée par votre requête. Ces pages expliquent les échecs de requêtes ; elles ne surveillent pas les limites de compte.
Pages de services associés
Chaque entrée indique sa propre couverture de collecte. Un service lié n’est pas nécessairement collecté automatiquement.
La date de vérification éditoriale concerne ce guide. Les heures de collecte des rapports actuels figurent sur les pages des services.