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.
Vérifications propres à chaque couche
Pour un 401
Vérifiez Authorization: Bearer ..., les guillemets ou espaces ajoutés, l’état de la clé et les anciens secrets du déploiement. Cette erreur survient généralement avant le routage du modèle.
Pour un 403
Avec la même clé, contrôlez les modèles autorisés, la liste IP, l’accès au groupe et la politique du compte. Si aucun canal n’a encore été choisi, changer de fournisseur ne corrige pas ce rejet antérieur.
Pour un 429
Déterminez si la limite appartient à la clé, au compte, au groupe ou à la route. Respectez Retry-After, appliquez une attente exponentielle avec aléa et bornez tentatives, durée totale et concurrence.
Pour un 499
Commencez par le client : signal d’annulation, onglet fermé, CDN, répartiteur et délais du proxy. Comparez l’heure d’annulation à la première sortie effective ; un 499 isolé ne prouve pas une panne de canal.
Distinguer les erreurs 5xx
Un 500 peut être un défaut déterministe d’adaptation, un 502 une réponse upstream invalide ou incomplète, un 503 une route temporairement indisponible et un 504 l’épuisement d’un budget de temps. Conservez le statut d’origine et ne relancez que les opérations sûres avec une limite stricte.
Preuves sûres pour le diagnostic
- identifiant de requête et heure UTC ;
- endpoint et mode de diffusion ;
- modèle demandé et groupe sélectionné ;
- statut HTTP et code d’erreur structuré ;
- durée totale et délai jusqu’à la première sortie effective ;
- indication d’une annulation côté client ;
- description expurgée des fonctions utilisées, telles que les outils ou images.
N’incluez pas la clé complète, l’invite, la réponse, le corps original, l’adresse e-mail ou l’IP en clair hors d’un processus sûr expressément approuvé.
Questions fréquentes
Un 403 prouve-t-il que le fournisseur est indisponible ?
Non. Compte, clé, modèle, groupe, IP ou politique fonctionnelle peuvent rejeter la requête avant toute sélection du fournisseur.
Un 499 est-il une erreur normale du modèle upstream ?
Non. Dans les journaux Modelflare, il représente une annulation downstream observée avant la fin de la réponse.
Faut-il relancer tous les 5xx ?
Non. Ne relancez que le travail répétable sans risque, bornez tentatives et durée totale, et conservez toujours la première erreur.