Taxonomie des erreurs de passerelle LLM : Distinguer les échecs d'authentification, de quota, de fournisseur et de sécurité

La taxonomie des erreurs de passerelle LLM fait la différence entre un incident maîtrisé et une tempête de tentatives coûteuses. Une passerelle ne doit pas traiter chaque appel de modèle échoué comme le même type d'erreur de fournisseur. Les informations d'identification invalides, les quotas épuisés, la surcharge du fournisseur, les requêtes mal formées, les refus de sécurité, les délais d'attente et les annulations par le client nécessitent tous des chemins de récupération différents.

L'erreur courante est d'envoyer chaque échec dans la même boucle de tentative et de repli. Cela peut masquer une clé révoquée, épuiser un plafond de dépenses, acheminer du contenu non sécurisé vers un autre fournisseur ou dupliquer le travail après qu'une réponse en streaming a déjà commencé. Une taxonomie pratique des erreurs de passerelle LLM donne aux équipes d'ingénierie, de produit et de finance un langage commun pour décrire ce qui s'est passé et ce que la passerelle doit faire ensuite.

Flatkey correspond à ce modèle de fonctionnement car son site public actuel positionne le produit comme une surface de passerelle unique pour l'accès aux modèles, le routage, la facturation, l'analyse de l'utilisation et les contrôles opérationnels. Utilisez cette surface partagée pour classer les échecs avant de choisir un comportement de nouvelle tentative, de mise en file d'attente, de repli ou de fermeture en cas d'échec.

Taxonomie des erreurs de passerelle LLM en un tableau

Commencez par la classe, pas seulement par le statut HTTP. La même famille de statuts peut signifier différentes choses selon les fournisseurs, les SDK et les formes de points de terminaison.

Cette taxonomie des erreurs de passerelle LLM est intentionnellement orientée vers l'action. Elle ne se contente pas d'étiqueter les erreurs pour les tableaux de bord. Elle décide quand le système peut dépenser plus de jetons, quand il doit demander à un propriétaire de corriger l'état et quand il doit s'arrêter.

Classifier avant de réessayer

Les documentations officielles des fournisseurs soutiennent la séparation de ces classes. Le guide des erreurs d'OpenAI distingue l'authentification invalide, les clés API incorrectes, les échecs de la liste d'autorisation IP, les limites de débit, l'épuisement du quota ou de la facturation, les erreurs de serveur, la surcharge, les erreurs de connexion SDK, les délais d'attente SDK, les requêtes mal formées, les refus de permission et les exceptions de limite de débit. Son guide sur les limites de débit recommande un backoff exponentiel aléatoire mais note également que les requêtes échouées comptent toujours dans les limites par minute.

La documentation des erreurs d'Anthropic sépare invalid_request_error, authentication_error, permission_error, not_found_error, request_too_large, rate_limit_error, api_error, et overloaded_error. Anthropic documente également les limites de débit 429 avec des conseils retry-after, et son guide sur les raisons d'arrêt inclut refusal comme condition d'arrêt au niveau du modèle.

Le dépannage de Gemini distingue les échecs d'authentification et de permission des erreurs 429 RESOURCE_EXHAUSTED, des erreurs internes 500 et de l'indisponibilité 503. La documentation sur les limites de débit de Gemini décrit les dimensions de requête, de jeton, de requête quotidienne et de dépense. Les paramètres de sécurité de Gemini exposent également les blocages de prompt, le finishReason du candidat et les safetyRatings, y compris un finishReason de SAFETY lorsque le contenu de la réponse est bloqué.

Ces observations mènent à une règle simple : une taxonomie des erreurs de passerelle LLM doit normaliser les signaux spécifiques au fournisseur en champs de décision avant que la passerelle ne choisisse une action.

Échecs d'authentification et d'autorisation

Les échecs d'authentification et d'autorisation doivent entraîner un arrêt immédiat. Réessayer avec une clé incorrecte ou un projet interdit ajoute généralement du bruit sans changer le résultat.

Normalisez ces signaux dans la classe d'authentification :

Dans une passerelle, les erreurs d'authentification doivent inclure owner_key, credential_id, project_id, provider, endpoint_family, requested_model et route_id. Évitez de journaliser les secrets bruts. L'incident doit indiquer quelle clé a échoué, quelle route a tenté l'appel et qui peut le corriger.

Le basculement (fallback) est généralement une mauvaise approche pour les échecs d'authentification. Si une équipe n'a pas approuvé un fournisseur, basculer silencieusement vers un autre peut contourner les politiques d'approvisionnement, de frontières des données ou de modèle. La réponse contrôlée est un échec clair, une alerte au propriétaire et un chemin de remédiation.

Échecs de quota et de limite de débit

Les échecs de quota et de limite de débit sont la catégorie la plus souvent affectée par une logique de relance vague. Un code 429 peut signifier une régulation de rafale, des limites de requêtes par minute, des limites de jetons par minute, des limites de requêtes quotidiennes, l'épuisement du budget mensuel, l'épuisement du crédit prépayé ou des limites basées sur les dépenses. Ces cas ne partagent pas un chemin de récupération unique.

Utilisez cette taxonomie des erreurs de passerelle LLM pour les décisions de quota :

La clé est de distinguer la régulation temporaire de l'épuisement du budget. Le backoff est utile lorsque le fournisseur vous demande de ralentir. Le backoff n'aide pas lorsque le compte n'a plus de crédit ou que la tâche ne peut pas respecter le budget de jetons disponible.

Associez cette section à la stratégie de relance des API d'IA de Flatkey lorsque vous avez besoin d'une liste de contrôle de relance plus détaillée. Gardez les tentatives de relance visibles dans les journaux afin que les équipes financières et opérationnelles puissent voir les dépenses de jetons en double.

Échecs de fournisseur et de transport

Les échecs de fournisseur et de transport sont différents des échecs de quota. Ils signifient que la requête peut être valide, la clé peut être valide et le budget peut être disponible, mais que la route n'a pas pu terminer l'appel.

Les signaux courants incluent :

Le basculement vers un autre fournisseur peut être utile ici, mais il nécessite un contrat. La route de basculement doit préserver la forme du point de terminaison, les outils, les besoins en sortie structurée, la fenêtre de contexte, la frontière des données, l'approbation du modèle et le plafond de coût. Si le streaming a déjà émis des jetons visibles, le comportement le plus sûr est souvent de s'arrêter et d'afficher un échec contrôlé au lieu de combiner la sortie d'une autre route.

Utilisez la fiabilité de l'API IA en streaming pour la récupération spécifique au streaming, et utilisez l'évaluation du repli de modèle avant de transformer les erreurs de fournisseur en changements de route automatiques.

Échecs de requête et de validation

Les échecs de requête et de validation ne sont généralement pas des incidents liés au fournisseur. Ils signifient que l'appelant a envoyé quelque chose que le point de terminaison ne peut pas traiter.

Les exemples incluent des champs obligatoires manquants, un JSON malformé, des paramètres non pris en charge, une mauvaise famille de points de terminaison, un ID de modèle non valide, un contexte trop long, un schéma d'outil non pris en charge, une modalité incompatible ou une entrée de fichier/image/vidéo qui ne respecte pas le contrat du point de terminaison.

La passerelle doit consigner ces champs :

Ne réessayez pas les échecs de validation non modifiés. Soit vous transformez la requête en une forme valide, soit vous retournez une erreur destinée aux développeurs qui nomme le champ à corriger. Lorsqu'une passerelle prend en charge plusieurs familles de points de terminaison, les erreurs de validation sont particulièrement importantes car une requête peut être valide pour un fournisseur et non valide pour un autre.

Échecs de sécurité et de politique

Les échecs de sécurité et de politique nécessitent leur propre classe car les nouvelles tentatives et le repli peuvent affaiblir accidentellement les garde-fous. Un refus de sécurité n'est pas une indisponibilité du fournisseur. Un blocage de modération n'est pas un épuisement de quota. Une sortie bloquée n'est pas une raison de continuer l'échantillonnage jusqu'à ce que la passerelle trouve une route qui émet le contenu interdit.

Normalisez ces signaux dans la classe de sécurité :

La règle pratique est simple : une taxonomie des erreurs de passerelle LLM ne doit jamais traiter la sécurité comme une panne de fournisseur récupérable. Le repli ne peut être acceptable que lorsque la route de repli préserve une politique de sécurité identique ou plus stricte et que l'objectif est de terminer une version sûre de la tâche, et non de contourner le blocage.

L'enregistrement d'erreur normalisé

Une taxonomie utile des erreurs de passerelle LLM transforme les échecs spécifiques au fournisseur en un seul enregistrement durable.

Ne réduisez pas cet enregistrement à une simple chaîne de caractères comme « L'appel LLM a échoué ». Cette chaîne ne suffit pas pour décider s'il faut faire une rotation de clé, attendre, recharger, utiliser une solution de repli, réviser une invite ou s'arrêter.

Un classifieur TypeScript simple

Le classifieur n'a pas besoin de connaître tous les détails du fournisseur dès le premier jour. Commencez avec des catégories explicites et une valeur par défaut qui échoue de manière prudente.

type ErrorClass =
  | "auth"
  | "quota"
  | "provider"
  | "request"
  | "safety"
  | "cancelled"
  | "unknown";

type GatewayErrorInput = {
  httpStatus?: number;
  providerErrorType?: string;
  providerErrorCode?: string;
  finishReason?: string;
  stopReason?: string;
  clientCancelled?: boolean;
  timeout?: boolean;
};

function classifyGatewayError(error: GatewayErrorInput): ErrorClass {
  const type = (error.providerErrorType || "").toLowerCase();
  const code = (error.providerErrorCode || "").toLowerCase();
  const stop = (error.stopReason || "").toLowerCase();
  const finish = (error.finishReason || "").toLowerCase();

  if (error.clientCancelled) return "cancelled";

  if (error.httpStatus === 401 || error.httpStatus === 403) return "auth";
  if (type.includes("auth") || type.includes("permission")) return "auth";
  if (code.includes("invalid_api_key") || code.includes("ip_not_authorized")) {
    return "auth";
  }

  if (error.httpStatus === 429) return "quota";
  if (type.includes("rate_limit") || code.includes("quota")) return "quota";
  if (code.includes("resource_exhausted")) return "quota";

  if (stop === "refusal" || finish === "safety") return "safety";
  if (code.includes("moderation") || code.includes("blocked")) return "safety";

  if (error.httpStatus === 400 || error.httpStatus === 422) return "request";
  if (type.includes("invalid_request") || type.includes("bad_request")) {
    return "request";
  }

  if (error.timeout) return "provider";
  if ([500, 502, 503, 504, 529].includes(error.httpStatus || 0)) {
    return "provider";
  }
  if (type.includes("overloaded") || type.includes("api_error")) {
    return "provider";
  }

  return "unknown";
}

Utilisez ceci uniquement comme point de départ. Les classifieurs de production doivent conserver les mappages spécifiques aux fournisseurs dans la configuration, les tests et l'examen des incidents, et non les enfouir uniquement dans le code de l'application.

Runbook : nouvelle tentative, mise en file d'attente, solution de repli ou échec fermé

Une fois la classe connue, la passerelle peut choisir l'action à entreprendre.

Ce tableau est le centre opérationnel de la taxonomie des erreurs de passerelle LLM. Il indique à la passerelle quand il est sûr de poursuivre le travail et quand cela devient un risque.

Comment appliquer cela dans Flatkey

Utilisez la taxonomie comme une liste de contrôle pour le déploiement plutôt que comme un projet de tableau de bord ponctuel.

1. Choisissez un flux de travail, tel que le chat d'assistance, l'extraction par lots, les tâches d'évaluation ou le trafic de l'assistant de code.
2. Définissez les familles de points de terminaison autorisées, les modèles, les routes de repli et les plafonds de coûts pour ce flux de travail.
3. Normalisez les erreurs de fournisseur dans les champs ci-dessus.
4. Rendez les échecs d'authentification et d'autorisation visibles par le propriétaire et non réessayables.
5. Séparez les limites de débit temporaires de l'épuisement du quota, des dépenses et de la limite quotidienne.
6. Exigez un contrat de repli avant de changer de fournisseur ou de modèle.
7. Traitez le refus de sécurité et la modération comme des résultats de politique, et non comme des pannes de fournisseur.
8. Enregistrez l'état de la sortie partielle avant toute nouvelle tentative ou tout repli.
9. Examinez les preuves d'utilisation et de routage dans Flatkey avant d'étendre à d'autres flux de travail.
10. Liez le guide opérationnel à la tarification de Flatkey afin que les opérateurs puissent vérifier le catalogue actuel et la surface de coûts.

L'instantané de l'API de tarification publique de Flatkey du 3 juillet 2026 a renvoyé 45 lignes de modèles, six identifiants de fournisseurs et des familles de points de terminaison prises en charge, notamment openai, anthropic, gemini et image-generation. Considérez ces informations uniquement comme des faits sources datés. La disponibilité des modèles, les prix et le comportement de routage doivent être revérifiés avant le déploiement en production.

FAQ

Qu'est-ce qu'une taxonomie des erreurs de passerelle LLM ?

Une taxonomie des erreurs de passerelle LLM est un ensemble normalisé de classes d'échec pour le trafic modèle-fournisseur. Elle distingue les échecs d'authentification, de quota, de fournisseur, de requête, de sécurité et d'annulation afin que la passerelle puisse choisir un comportement de nouvelle tentative, de mise en file d'attente, de repli ou de basculement en mode fermé.

Pourquoi ne pas réessayer chaque erreur d'API LLM ?

Réessayer chaque erreur peut aggraver l'incident. Cela peut amplifier les limites de débit, dépenser plus de jetons après l'épuisement du quota, masquer les échecs d'identifiants, dupliquer la sortie partielle ou contourner les blocages de sécurité. La taxonomie décide quand une nouvelle tentative est réellement autorisée.

Les refus de sécurité doivent-ils déclencher un repli ?

Pas par défaut. Les refus de sécurité, les blocages de modération, les blocages de prompt et finishReason: SAFETY doivent être traités comme des résultats de politique. Le repli ne doit jamais être utilisé pour trouver une route de sécurité plus faible.

Comment une passerelle LLM doit-elle classer les échecs de quota ?

Séparez la régulation de débit temporaire de l'épuisement des dépenses, des crédits prépayés, des limites quotidiennes, des limites de jetons et des limites de projet. La régulation temporaire peut utiliser une temporisation limitée ou des files d'attente. Un budget épuisé entraîne généralement un basculement en mode fermé jusqu'à ce qu'un propriétaire approuve une capacité supplémentaire.

Comment Flatkey aide-t-il avec une taxonomie des erreurs de passerelle LLM ?

Flatkey offre aux équipes une surface de passerelle unique pour l'accès aux modèles, le routage, la facturation, l'analyse de l'utilisation et les contrôles opérationnels. Utilisez-la pour maintenir des classes d'erreurs normalisées liées aux clés des propriétaires, aux familles de points de terminaison, aux modèles demandés, aux modèles servis et aux preuves d'utilisation.

Commencez avec un seul flux de travail, définissez votre taxonomie des erreurs de passerelle LLM, puis obtenez une clé et testez les cas d'authentification, de quota, de fournisseur, de requête, de sécurité et d'annulation avant que le trafic de production ne dépende de la récupération automatique.