Guide des erreurs d’API d’IA : 401, 403, 429 et 5xx

Diagnostiquez authentification, politique d’accès, limites de débit, annulations client et pannes des fournisseurs amont, puis décidez quand réessayer sans risque.

Guide des erreurs d’API d’IA : 401, 403, 429 et 5xx

Les erreurs d’API d’IA sont plus faciles à diagnostiquer lorsque le code de statut est considéré comme le point de départ d’une analyse, et non comme la cause complète. Avant toute nouvelle tentative, conservez l’ID de requête, l’horodatage, l’endpoint, le modèle, le nom de la clé API, le groupe sélectionné, le corps de la réponse et les mesures temporelles.

L’objectif est d’identifier la couche qui a refusé ou interrompu la requête : client, authentification, politique d’accès, validation du protocole, routage, backend du modèle ou connexion en aval.

Ce qu’indiquent généralement les codes de statut courants

Statut Première interprétation Première action
400 Forme de requête, champ ou contrat de protocole non valide Comparer le contenu de la requête avec l’endpoint sélectionné ; ne pas réessayer sans modification
401 Identifiants absents, mal formés, désactivés, expirés ou non valides Vérifier l’en-tête Authorization et la clé actuelle
403 Authentification réussie, mais blocage par le compte, le modèle, le groupe, l’IP ou une politique Vérifier les restrictions de la clé et l’accès au modèle et au groupe avant de tester les canaux
404 Chemin d’endpoint incorrect ou identifiant de modèle indisponible Vérifier l’URL de base, le chemin et la liste des modèles obtenue avec authentification
429 Limite de débit, de quota ou de routes éligibles Examiner le quota et les limites du groupe ; utiliser un backoff borné ou le repli configuré
499 Le client en aval s’est déconnecté ou a annulé avant la fin Examiner les échéances du client, les interruptions, les proxys et le délai de première sortie
500 Échec du traitement interne ou de l’adaptateur Conserver l’ID de requête ; ne réessayer que si l’opération est sûre
502/503 Réponse incorrecte du fournisseur amont, route indisponible ou problème de capacité temporaire Vérifier les éléments liés à la route et recourir à un repli ou à des nouvelles tentatives bornés
504 Un budget de temps de la passerelle ou du fournisseur amont a expiré Comparer les délais de première sortie et le temps total aux échéances du client

Ces interprétations sont des points de départ pour le diagnostic. Le corps de l’erreur et l’enregistrement de la requête déterminent la cause réelle d’un appel donné.

Diagnostiquer un 401 avant de changer de modèle

Un 401 survient normalement avant tout routage utile vers un modèle. Vérifiez les points suivants :

  • l’en-tête utilise Authorization: Bearer ... ;
  • l’application n’a pas ajouté de guillemets, d’espaces ou de valeur fictive ;
  • la clé est activée et n’a pas expiré ;
  • la requête est envoyée à l’hôte Modelflare prévu ;
  • aucun gestionnaire de secrets ni déploiement n’a conservé une ancienne clé remplacée lors d’une rotation.

Ne collez pas la clé complète dans des journaux ou des messages adressés à l’assistance. Si une exposition est possible, reproduisez le problème avec une clé de test dédiée, puis révoquez l’identifiant compromis.

Diagnostiquer d’abord un 403 comme un échec de politique d’accès

Un 403 ne signifie pas automatiquement qu’un fournisseur amont a refusé la requête. L’authentification peut réussir alors que l’accès échoue avant la sélection du canal, car :

  • la clé restreint le modèle demandé ;
  • la liste d’IP autorisées de la clé n’inclut pas l’adresse IP observée du client ;
  • le compte ne peut pas utiliser le groupe de modèles sélectionné ;
  • l’utilisateur ou la clé est désactivé par une politique ;
  • la fonctionnalité demandée n’est pas autorisée pour cette route.

Récupérez /v1/models avec la même clé, examinez ses limites de groupe et de modèles, et comparez le code d’erreur exact. Si aucun canal n’a été sélectionné, changer de canal de fournisseur amont ne peut pas corriger la décision de politique prise plus tôt.

Diagnostiquer un 429 sans déclencher une avalanche de nouvelles tentatives

Un 429 est un signal de capacité ou de politique, et non une invitation à réessayer immédiatement dans une boucle serrée. Déterminez si la limite relève du quota de la clé, du compte, du groupe de modèles ou de la route sélectionnée.

Pour les limites de débit qui autorisent une nouvelle tentative :

  1. respectez Retry-After lorsqu’il est présent ;
  2. utilisez un backoff exponentiel avec jitter ;
  3. plafonnez le nombre de tentatives et la durée totale écoulée ;
  4. maintenez le nombre de requêtes simultanées de l’application sous une limite connue ;
  5. n’utilisez des groupes de repli ordonnés que s’ils préservent le modèle et le protocole demandés.

Créer davantage de clés API ne permet pas forcément de contourner une limite de requêtes au niveau du compte ou du groupe.

Diagnostiquer un 499 en partant de l’appelant

Modelflare peut enregistrer un 499 lorsque la connexion du client en aval se termine avant la fin de la réponse. Commencez par l’appelant :

  • Un signal d’interruption (abort) a-t-il été déclenché ?
  • Le client, l’équilibreur de charge, le CDN ou le proxy inverse a-t-il atteint un délai d’inactivité ou un délai total ?
  • L’utilisateur a-t-il fermé la page ou arrêté l’agent ?
  • Le flux a-t-il produit un événement d’outil sans texte visible ?
  • Combien de temps s’est-il écoulé avant la première sortie effective ?

Un enregistrement 499 ne suffit pas à établir une panne de canal. Comparez les autres requêtes de la même période et du même modèle ou groupe avant de modifier la politique de routage.

Distinguer les échecs 5xx par couche

Pour les 5xx, conservez le statut et les détails d’erreur d’origine au lieu de convertir chaque échec en erreur 500 générique côté client.

  • Une erreur 500 de validation ou d’adaptateur peut être déterministe et se reproduire si rien ne change.
  • Une erreur 502 peut indiquer une réponse non valide ou incomplète du fournisseur amont.
  • Une erreur 503 peut indiquer l’absence de route éligible ou une indisponibilité temporaire.
  • Une erreur 504 indique qu’un budget de temps a expiré, mais la couche responsable reste à identifier.

Utilisez les mesures temporelles de la requête, le groupe sélectionné, les informations sur le canal dont dispose l’assistance et les requêtes voisines pour distinguer une réponse défectueuse isolée d’un problème durable sur une route.

Décider s’il faut réessayer

Catégorie d’échec Décision par défaut
Contenu non valide ou protocole non pris en charge Corriger la requête ; ne pas réessayer sans modification
Clé non valide ou accès refusé Corriger les identifiants ou la politique ; ne pas réessayer sans modification
Quota épuisé Augmenter ou réattribuer délibérément le quota ; ne pas boucler
Limite de débit Réessayer avec un backoff borné lorsque c’est autorisé
502/503/504 temporaire Réessayer le travail idempotent avec un budget de tentatives strict
Annulation par le client Réessayer uniquement si l’utilisateur souhaite toujours le résultat et que les doublons sont sans risque
Effet de bord d’un outil ou d’une écriture Exiger une idempotence au niveau de l’application avant toute répétition

Les nouvelles tentatives créent du travail et peuvent engendrer de nouveaux coûts. Enregistrez chaque tentative et évitez de masquer l’échec initial derrière une réussite ultérieure.

Éléments à recueillir en toute sécurité

Pour l’assistance ou l’analyse d’un incident, relevez :

  • l’ID de requête et l’horodatage UTC ;
  • l’endpoint et le mode de streaming ;
  • le modèle demandé et le groupe sélectionné ;
  • le statut HTTP et le code d’erreur structuré ;
  • le temps total et le délai jusqu’à la première sortie effective ;
  • le fait que l’appelant ait annulé ou non ;
  • une description expurgée des fonctionnalités utilisées par la requête, comme les outils ou une entrée d’image.

N’incluez pas la clé API complète, le prompt, le contenu de la réponse, le corps brut de la requête, l’adresse e-mail ni l’adresse IP en clair, sauf si une procédure sécurisée approuvée l’exige expressément.

Après avoir localisé la couche en échec, consultez Routage fiable des API d’IA pour concevoir les replis, et le guide du streaming pour les échecs liés aux événements et aux délais d’expiration.

Questions fréquentes

Un 403 prouve-t-il qu’un fournisseur est en panne ?

Non. Un 403 peut provenir d’une politique de compte, de clé, de modèle, de groupe, d’IP ou de fonctionnalité, avant même la sélection d’une route vers un fournisseur amont. Vérifiez d’abord l’enregistrement de la requête et le code d’erreur.

Un 499 est-il une erreur standard du modèle d’un fournisseur amont ?

Non. Dans les enregistrements de requêtes de Modelflare, il représente une annulation en aval observée avant la fin de la réponse. Examinez les échéances de l’appelant et du proxy avant de le considérer comme un échec du modèle.

Faut-il réessayer chaque réponse 5xx ?

Non. Ne réessayez que les opérations qui peuvent être répétées sans risque, appliquez un budget limité de tentatives et de temps, et conservez la première erreur. Les problèmes déterministes d’adaptateur ou de requête ne disparaîtront pas en répétant l’appel.