Erreurs des API d’IA : 401, 403, 429 et 5xx
Diagnostiquez authentification, politiques, limites, annulations et erreurs upstream par couche, puis décidez des reprises sûres.
Un statut HTTP ouvre le diagnostic d’une API d’IA, mais n’en donne pas toute la cause. Avant une nouvelle tentative, conservez ID, heure UTC, endpoint, modèle, nom de clé, groupe, erreur structurée et délais. Localisez ensuite le rejet dans le client, l’authentification, la politique, le protocole, la route, le backend ou la connexion downstream.
Première interprétation
| Statut | Lecture initiale | Première action |
|---|---|---|
| 400 | Payload ou contrat invalide | Corriger, ne pas répéter à l’identique |
| 401 | Clé absente, incorrecte ou expirée | Vérifier Authorization et la clé actuelle |
| 403 | Politique de compte, modèle, groupe ou IP | Contrôler les restrictions avant les canaux |
| 404 | Chemin ou modèle erroné | Vérifier Base URL et /v1/models |
| 429 | Limite de quota, débit ou route | Identifier la limite et attendre avec bornes |
| 499 | Le client a annulé avant la fin | Examiner deadlines, Abort, proxy et première sortie |
| 502/503/504 | Réponse upstream, disponibilité ou temps | Garder les preuves et réessayer avec limites |
Diagnostiquer par couche
401 se produit souvent avant le routage. Vérifiez Authorization: Bearer ..., l’état de la clé, l’hôte et les anciens secrets du déploiement. Ne copiez jamais la clé entière dans un journal ou ticket.
403 ne prouve pas un refus du fournisseur. Limites de modèles, liste IP, droit de groupe ou politique de compte peuvent agir avant le choix du canal. Appelez /v1/models avec la même clé et lisez le code exact.
Pour 429, identifiez si la limite appartient à la clé, au compte, au groupe ou à la route. Respectez Retry-After, appliquez un backoff exponentiel avec jitter et bornez tentatives, durée et concurrence. Multiplier les clés ne contourne pas forcément une limite de compte.
499 indique la fin de la connexion downstream. Commencez par Abort, navigateur, CDN, load balancer et proxy ; comparez la première sortie effective. Un enregistrement isolé ne prouve pas une panne du canal.
Décider d’une nouvelle tentative
- Requête, clé ou accès invalide : corriger, ne pas répéter.
- Limite de débit : backoff borné seulement si permis.
- 502, 503 ou 504 temporaire : uniquement travail idempotent, budget strict.
- Annulation : vérifier que le résultat est encore requis et sans effet dupliqué.
- Outil ou écriture : imposer l’idempotence applicative.
Chaque essai peut créer du travail et du coût. Partagez ID, heure, endpoint, streaming, modèle, groupe, statut, code et délais ; pas la clé complète, prompt, réponse, body, email ou IP en clair. Poursuivez avec Routage fiable et le guide du streaming.