Un disjoncteur de passerelle API LLM empêche une application d’envoyer à répétition du trafic vers une route qui est déjà en échec. Sans cette protection, un délai d’attente peut déclencher des retries, les retries peuvent déclencher des tentatives de repli, les tentatives de repli peuvent provoquer davantage d’erreurs chez le fournisseur, et l’application peut transformer un incident amont en boucle de défaillance chez le fournisseur.
L’objectif n’est pas de remplacer les retries ou le repli de modèle. L’objectif est de décider quand une route est suffisamment dégradée pour que la passerelle cesse d’essayer pendant une courte fenêtre, envoie plus tard une sonde contrôlée, et choisisse un résultat plus sûr pendant que le disjoncteur est ouvert : repli, mise en file d’attente, dégradation ou échec fermé.
Flatkey est pertinent parce que flatkey.ai positionne publiquement le produit autour d’une seule clé API, d’une URL de base compatible OpenAI à https://router.flatkey.ai/v1, du routage, de la facturation unifiée, des analyses d’utilisation, des contrôles du tableau de bord, du basculement automatique, de l’équilibrage de charge et des limites de quota. Ce sont des points centraux utiles pour le travail sur la fiabilité. Ils ne suppriment pas la nécessité de définir une politique claire de disjoncteur de passerelle API LLM pour les workflows de votre propre application.
Réponse rapide : ce qu’un disjoncteur de passerelle API LLM doit faire
Un disjoncteur de passerelle API LLM pratique comporte trois états de routage et un chemin de fermeture en cas d’échec. Gardez la politique suffisamment simple pour que les ingénieurs d’astreinte puissent l’expliquer pendant un incident.
| État | Comportement de la passerelle | Ce qui le fait basculer | Éléments à consigner |
|---|---|---|---|
| Fermé | Le trafic peut utiliser le fournisseur, le modèle, la famille de points de terminaison, le compte ou le groupe de routes. | Le taux d’erreur, le taux de timeout, la latence, les réponses de surcharge ou les sondes de santé échouées dépassent le seuil. | ID de la politique de routage, modèle sélectionné, fournisseur, famille de points de terminaison, latence, code d’état, nombre de tentatives et coût. |
| Ouvert | La passerelle cesse d’envoyer le trafic normal vers la route défaillante pendant une fenêtre de refroidissement. | La période de refroidissement expire, ou un opérateur autorise manuellement une sonde. | Raison du disjoncteur, heure d’ouverture, nombre de tentatives bloquées, route de repli, décision de mise en file d’attente ou raison de fermeture en cas d’échec. |
| À moitié ouvert | La passerelle autorise un nombre limité de requêtes de sonde avant de rétablir le trafic. | Des sondes réussies ferment le disjoncteur ; des sondes échouées le rouvrent. | Taille de l’échantillon de sonde, workflow de sonde, résultat de la sonde, latence, utilisation et approbation du propriétaire de la route. |
| Fermeture en cas d’échec | La passerelle refuse d’acheminer la requête parce que le problème ne relève pas de la santé du fournisseur. | Risque d’authentification, de politique, de quota, de sécurité, de frontière de données, de requête invalide ou d’effet secondaire d’outil. | Raison de l’arrêt, propriétaire, message visible par l’utilisateur et chemin de remédiation. |
Pourquoi les nouvelles tentatives créent des boucles d’échec côté fournisseur
Les nouvelles tentatives sont utiles lorsqu’une requête échoue pour une raison transitoire. Elles deviennent dangereuses lorsque chaque requête utilisateur génère plusieurs appels amont supplémentaires, en particulier lors d’une panne ou d’une surcharge du fournisseur. Une boucle de réessais peut consommer des limites de débit, épuiser le quota, augmenter la latence et masquer l’échec initial derrière une erreur finale.
Un disjoncteur change la question des réessais. Au lieu de demander : « Cette requête doit-elle être réessayée encore une fois ? », la passerelle se demande : « Cette route est-elle suffisamment saine pour recevoir davantage de trafic maintenant ? » Cette vue au niveau de la route est importante pour les charges de travail LLM, car chaque requête peut être coûteuse, longue à exécuter, en streaming, utiliser des outils et être visible par le client.
Le modèle de conception cloud de Microsoft pour les disjoncteurs décrit la même idée fondamentale pour les services distants : après des échecs répétés, le circuit s’ouvre afin que l’application ne continue pas à tenter une opération susceptible d’échouer. Pour une route d’IA, le même modèle nécessite des limites spécifiques aux LLM : comportement du modèle, famille de point de terminaison, consommation de jetons, état du streaming, effets de bord des outils, classe de données et approbation du fallback.
Classifiez les erreurs avant qu’elles n’atteignent le disjoncteur
Le moyen le plus rapide de construire un mauvais disjoncteur de circuit d’API IA est de compter chaque échec comme un problème de santé du fournisseur. Cela crée de faux positifs. Cela peut aussi masquer des problèmes que le propriétaire de l’application doit corriger.
| Erreur ou événement | Décision du disjoncteur | Raison | Résultat par défaut |
|---|---|---|---|
| Fournisseur 500, 503, surcharge, indisponible, échec de connexion, délai d’attente amont répété | Compter dans la santé de la route. | Ce sont des signaux plausibles de santé du fournisseur, de la route, de la capacité ou du réseau. | Réessayer dans une limite stricte, puis ouvrir le disjoncteur de la route si les seuils sont dépassés. |
| 429 limite de débit des requêtes | Classer avec soin. | Un signal de surcharge à l’échelle du fournisseur et une rafale créée par l’application nécessitent des traitements différents. | Ralentir, réduire le débit ou n’ouvrir que la route ciblée qui est réellement saturée. |
| 429 quota mensuel, crédits épuisés ou limite de dépenses | Ne pas compter comme santé du fournisseur. | Il s’agit d’une condition de budget ou de propriétaire de compte. | Échouer de manière fermée, alerter le responsable du budget ou router seulement si un budget préapprouvé existe. |
| 401 authentification, clé incorrecte, appartenance à l’organisation, liste d’autorisation IP, région non prise en charge | Ne pas compter comme santé du fournisseur. | La requête n’est pas autorisée à utiliser la route. | Échouer de manière fermée et corriger les identifiants, le compte, l’adresse IP ou la politique de région. |
| Requête invalide, paramètre non pris en charge, modèle non pris en charge, schéma mal formé | Ne pas compter comme santé du fournisseur. | L’application a envoyé une forme de requête que la route ne peut pas servir. | Corriger la requête ou choisir un modèle compatible avant le routage. |
| Blocage de sécurité, modération, DLP, conformité ou de classe de données non approuvée | Ne jamais contourner avec un fallback. | Le routage vers un autre modèle pourrait franchir une frontière de politique. | Échouer de manière fermée et enregistrer la décision de politique. |
| Outil déjà exécuté, flux partiel déjà affiché, utilisateur ayant annulé la requête | Ne pas rejouer silencieusement. | L’application peut créer des effets secondaires en double ou fusionner deux sorties de modèle. | Marquer comme incomplet, exiger une nouvelle tentative explicite de l’utilisateur ou utiliser un chemin de récupération idempotent. |
Le guide des codes d’erreur d’OpenAI est un exemple utile de l’importance de cette taxonomie : il sépare les problèmes d’authentification et de liste d’autorisation IP, les problèmes de région non prise en charge, les limites de débit, l’épuisement du quota, les erreurs serveur, la surcharge et les ralentissements soudains du débit de requêtes. La documentation d’Anthropic et de Google Gemini fait des distinctions similaires entre les limites de débit, les conditions de surcharge/indisponibilité, les requêtes invalides et les problèmes d’autorisation ou de quota. Votre disjoncteur de circuit de passerelle d’API LLM devrait garder ces classes séparées avant d’ouvrir une route.
Délimitez le breaker au plus petit chemin qui explique l’échec
Un breaker trop large entraîne des temps d’arrêt inutiles. Un breaker trop étroit laisse se poursuivre, via des chemins proches, la même boucle de défaillance du fournisseur. Délimitez le breaker à la plus petite dimension de route qui explique l’incident.
| Périmètre | À utiliser lorsque | Risque en cas de mauvais périmètre |
|---|---|---|
| Fournisseur | Plusieurs modèles du même fournisseur sont indisponibles ou surchargés. | Trop large si un seul modèle, compte ou famille de points de terminaison est en échec. |
| Modèle | Une famille de modèles présente des erreurs 5xx répétées, des timeouts ou des erreurs de route non prises en charge. | Trop étroit si le compte amont ou le fournisseur est saturé. |
| Famille de points de terminaison | Chat fonctionne, mais les routes Responses, image, video, Anthropic Messages ou Gemini se comportent différemment. | Mélanger les familles de points de terminaison peut masquer des défaillances spécifiques au protocole. |
| Compte, groupe, région ou chemin fournisseur | Un seul compte amont, groupe de routage, région ou chemin fournisseur est en échec. | Ne pas isoler peut griller de la capacité saine ailleurs. |
| Workflow | Les appels d’outils, le streaming, les jobs batch ou le chat destiné aux clients ont des règles de sécurité et de relecture différentes. | Une route sûre pour l’enrichissement batch peut être dangereuse pour des flux utilisateurs en direct. |
Pour les utilisateurs de Flatkey, cela signifie que vous devez tester à partir du workflow et de la route que vous prévoyez réellement d’utiliser. L’instantané actuel de l’API de tarification Flatkey pour cet article a renvoyé 638 lignes de modèles, 23 fournisseurs et des familles de points de terminaison pour OpenAI chat completions, OpenAI Responses, Anthropic messages, Gemini generateContent, la génération d’images et OpenAI video. Considérez cela comme une preuve datée du 18 juin 2026, et non comme un contrat de routage permanent.
Définir des seuils adaptés au trafic LLM
Un disjoncteur de passerelle API LLM ne doit pas s’ouvrir à cause d’une seule défaillance isolée. Il ne doit pas non plus attendre que chaque requête client échoue. Utilisez des seuils qui combinent volume minimal de trafic, ratio d’échecs, latence et période de refroidissement.
| Seuil | Point de départ pratique | Pourquoi c’est important |
|---|---|---|
| Taille minimale de l’échantillon | N’ouvrir qu’après avoir observé suffisamment de requêtes ou de sondes. | Empêche qu’une seule complétion coûteuse ouvre une route globale. |
| Ratio d’échecs | Suivre séparément les échecs amont réessayables et les échecs propres à l’application. | Évite que les erreurs d’authentification, de quota et de requête mal formée dégradent l’état de santé de la route. |
| Seuil de latence ou de délai d’attente | Utiliser des budgets de délai d’attente spécifiques à l’endpoint pour les chemins chat, streaming, image et vidéo. | Un bon seuil pour le chat peut être inadapté à la vidéo ou à la génération par lot. |
| Temps de refroidissement à l’ouverture | Maintenir la route ouverte assez longtemps pour stopper les tempêtes de retries, puis sonder. | Protège à la fois le fournisseur et votre propre file de requêtes. |
| Limite de sondes en mode semi-ouvert | Autoriser un petit nombre contrôlé de requêtes de test avant de refermer. | Empêche une reprise massive du trafic lorsqu’un fournisseur n’est que partiellement rétabli. |
| Plafond de coûts | Définir une dépense estimée maximale pour les retries, le fallback et les sondes. | Évite qu’une récupération de la fiabilité se transforme en incident de facturation. |
Les limites de débit font partie de la discussion sur les seuils. Le guide des limites de débit d’OpenAI explique que les limites de débit protègent contre les abus, garantissent un accès équitable et aident à gérer la charge agrégée. Si votre application continue à réessayer sur une route limitée en débit, votre propre schéma de trafic peut devenir l’incident. Le disjoncteur de passerelle API LLM doit fonctionner avec le pacing côté client, la mise en file d’attente et les contrôles de quota, et non s’y opposer.
Décidez de ce qui se passe pendant que le disjoncteur est ouvert
Ouvrir un disjoncteur n’est utile que si la passerelle dispose d’une action suivante définie. Ne laissez pas chaque route ouverte basculer automatiquement vers n’importe quel modèle disponible.
| Action à l’état ouvert | À utiliser quand | Garde-fou requis |
|---|---|---|
| Route de secours | Le modèle ou fournisseur de secours est déjà approuvé pour le flux de travail. | Exécutez les mêmes vérifications d’évaluation, de schéma, d’outil, de limite de données et de coût avant la mise en production. |
| Mettre en file d’attente | La tâche est asynchrone ou l’expérience utilisateur peut tolérer un délai. | Conservez les métadonnées du propriétaire, du client, du modèle, du coût et des tentatives. |
| Dégrader | Un résultat partiel à plus faible risque est acceptable, comme une réponse mise en cache ou une fonctionnalité réduite. | Rendez l’état dégradé visible pour l’application et les journaux. |
| Échouer de manière fermée | La requête comporte un risque de politique, de budget, de sécurité, d’authentification, de région ou d’effet de bord. | Renvoyez une erreur claire et alertez le bon responsable au lieu d’essayer un autre modèle. |
La documentation publique de Vercel AI Gateway décrit les solutions de secours des modèles comme un schéma de passerelle avec des modèles de secours ordonnés. Utilisez cela uniquement comme preuve de catégorie. Dans votre propre pile, le secours est une décision d’approbation distincte. Le disjoncteur décide si une route est actuellement saine ; le secours décide si une autre route est autorisée à servir la même requête.
Le streaming et les appels d’outil nécessitent des arrêts supplémentaires
Le streaming facilite la dissimulation d’une boucle d’échec d’un fournisseur. Si l’application redémarre silencieusement une requête après une sortie partielle, l’utilisateur peut voir une réponse fusionnée provenant de deux tentatives. Les appels d’outil ajoutent un second problème : une nouvelle tentative ou un fallback peut dupliquer un remboursement, une mise à jour de ticket, un e-mail, une écriture en base de données ou une action externe.
Utilisez ces règles dans la politique du disjoncteur de la passerelle API LLM :
- Avant la première sortie : une nouvelle tentative ou un fallback peut être autorisé si la route est approuvée et si le disjoncteur est fermé ou semi-ouvert.
- Après la première sortie : marquez le flux comme incomplet et exigez une nouvelle tentative explicite de l’utilisateur au lieu d’un fallback silencieux.
- Après l’exécution d’un outil : ne rejouez pas sauf si l’outil est idempotent et que l’opération dispose d’une clé de relecture.
- Après un blocage de politique : échouez fermé. Ne routez pas vers un autre modèle pour contourner le blocage.
Cela s’associe aux guides stratégie de nouvelle tentative de l’API d’IA, liste de contrôle des fallbacks de modèle et équilibrage de charge et basculement de l’API d’IA. Le disjoncteur devrait partager la même taxonomie des échecs que ces playbooks.
Champs d’observabilité pour la revue du coupe-circuit
Si une requête réussit uniquement parce que la passerelle a silencieusement contourné une route défaillante, l’incident doit tout de même être visible. La documentation de l’AI Gateway de Cloudflare fournit un exemple public de modèles d’observabilité pour une passerelle IA : les journaux de requêtes peuvent inclure le fournisseur, le statut, les jetons, le coût et la durée, et les métadonnées personnalisées peuvent étiqueter les requêtes pour un filtrage ultérieur. Vos journaux de passerelle devraient fournir le même niveau de preuves de route pour les décisions du coupe-circuit.
| Champ | Pourquoi les opérateurs en ont besoin |
|---|---|
| ID et version de la politique du coupe-circuit | Indique quelle règle a ouvert, fermé ou contourné la route. |
| État du coupe-circuit au moment de la décision | Explique si la route était fermée, ouverte, semi-ouverte ou en échec fermé. |
| Modèle demandé, modèle sélectionné, fournisseur, compte, groupe et famille d’endpoint | Sépare l’intention de l’utilisateur de la décision de routage de la passerelle. |
| Classe d’erreur par tentative | Distingu e les échecs en amont des erreurs d’authentification, de quota, de requête invalide, de politique et d’outil. |
| Latence, délai d’attente, nombre de tentatives et résultat de la sonde | Indique si la route a échoué lentement, échoué rapidement ou s’est rétablie pendant le sondage en semi-ouverture. |
| Drapeau de sortie partielle et état des effets secondaires de l’outil | Empêche les incidents cachés de sortie mixte ou d’action dupliquée. |
| Utilisation, coût, propriétaire du quota et disposition finale | Relie le rétablissement de la fiabilité aux dépenses, aux budgets et à la responsabilité. |
L’article compagnon journaux d’observabilité de l’API IA va plus loin sur la journalisation des incidents. Pour les coupe-circuits, donnez la priorité à l’état de la route et à la raison exacte pour laquelle une requête a été bloquée, sondée, routée, mise en file d’attente ou a échoué en mode fermé.
Un plan de déploiement Flatkey pour les politiques de disjoncteur
Utilisez cette approche progressive avant de vous fier à un disjoncteur de passerelle API LLM pour le trafic client via Flatkey ou toute passerelle compatible OpenAI.
- Créer une clé de staging : gardez les tests du disjoncteur séparés du trafic client de production.
- Confirmer la route de base : pointez un client compatible OpenAI vers
https://router.flatkey.ai/v1et vérifiez le modèle, la famille de point de terminaison, la ligne d’utilisation et la visibilité dans le tableau de bord. - Capturer l’état du catalogue de routes : enregistrez la page de tarification Flatkey et la réponse de l’API de tarification à la date de déploiement afin que les hypothèses de route et de tarification soient auditables.
- Définir la taxonomie des erreurs : décidez quelles erreurs comptent dans la santé de la route et lesquelles échouent de manière fermée avant que le disjoncteur ne les voie.
- Commencer avec un seul flux de travail : appliquez le disjoncteur à une seule route de modèle, une seule famille de point de terminaison et une seule classe de trafic avant d’élargir.
- Forcer des tests d’échec : simulez un délai d’attente du fournisseur, un 500, un 503, un 429 de taux de requêtes, un épuisement du quota, une échec d’authentification, une requête mal formée, un flux partiel et un effet secondaire d’outil.
- Vérifier le comportement en état ouvert : confirmez que les actions de secours, de mise en file d’attente, de dégradation ou d’échec fermé correspondent à la matrice d’approbation.
- Examiner les journaux et la facturation : confirmez que l’état du disjoncteur, la route sélectionnée, l’utilisation, le coût et le propriétaire du quota sont visibles après chaque test.
- Prévoir un retour arrière : désactivez la politique si elle s’ouvre de manière trop large, masque les erreurs détenues par l’application ou entraîne des dépenses inattendues.
Modèle de politique de disjoncteur
Ce modèle n’est pas un contrat d’API Flatkey. Considérez-le comme un support de revue pour les responsables de l’ingénierie, du produit, des finances et de la sécurité.
{
"policy_id": "support-chat-provider-breaker-v1",
"workflow": "customer-support-chat",
"environment": "production",
"route_scope": {
"provider": "primary-provider",
"model": "primary-approved-model",
"endpoint_family": "openai-chat-completions",
"traffic_class": "customer-visible-stream"
},
"count_toward_breaker": [
"upstream_5xx",
"provider_overloaded",
"provider_unavailable",
"upstream_timeout",
"connection_reset"
],
"fail_closed_before_breaker": [
"auth_error",
"ip_allowlist_error",
"unsupported_region",
"quota_exhausted",
"invalid_request",
"schema_incompatible",
"safety_or_policy_block",
"unapproved_data_class",
"tool_side_effect_already_committed"
],
"thresholds": {
"window_seconds": 60,
"minimum_requests": 20,
"failure_ratio_to_open": 0.5,
"timeout_ratio_to_open": 0.4,
"open_cooldown_seconds": 90,
"half_open_probe_requests": 3,
"max_total_attempts_per_request": 2
},
"open_state_action": {
"default": "fail_closed",
"allowed_fallback_policy_ids": [
"support-chat-fallback-v1"
],
"allow_after_partial_output": false,
"allow_after_tool_side_effect": false
},
"logging": {
"record_breaker_state": true,
"record_route_scope": true,
"record_error_class_per_attempt": true,
"record_probe_results": true,
"record_usage_cost_and_quota_owner": true
}
}Questions fréquentes
Qu’est-ce qu’un disjoncteur de passerelle API LLM ?
Un disjoncteur de passerelle API LLM est une politique de santé de route qui empêche le trafic normal d’atteindre un modèle, un fournisseur, un compte ou une famille de points de terminaison en mauvaise santé après des échecs répétables récupérables. Il s’ouvre pendant une fenêtre de refroidissement, autorise des sondes limitées en demi-ouverture, et se referme uniquement après que la route semble à nouveau saine.
Quelles erreurs de l’API LLM devraient ouvrir un disjoncteur ?
Les erreurs 5xx côté fournisseur, la surcharge, les réponses d’indisponibilité, les échecs de connexion et les délais d’attente amont répétés sont des candidats typiques. Les erreurs d’authentification, les échecs de liste d’autorisation IP, les régions non prises en charge, les quotas épuisés, les requêtes mal formées, les blocages de politique et les effets de bord des outils devraient généralement échouer en mode fermé plutôt que d’ouvrir un disjoncteur de santé du fournisseur.
En quoi un disjoncteur diffère-t-il d’une tentative de nouvelle exécution ou d’un repli ?
La nouvelle tentative décide si une requête doit être essayée à nouveau. Le repli décide si une autre route approuvée peut traiter la requête. Un disjoncteur décide si une route doit recevoir du trafic normal tout court alors qu’elle semble en mauvaise santé.
Les disjoncteurs devraient-ils s’appliquer aux réponses LLM en streaming ?
Oui, mais avec des limites plus strictes. Un disjoncteur peut protéger la route avant le premier jeton visible. Après une sortie partielle ou un effet de bord d’un outil, l’application ne devrait pas rejouer silencieusement la requête ni effectuer un repli, sauf si le workflow est explicitement conçu pour une récupération idempotente.
Vérification finale avant d’activer le disjoncteur
Avant d’activer un disjoncteur de passerelle d’API LLM, posez une question : si cette route s’ouvre pendant un incident chez un fournisseur, l’équipe peut-elle expliquer ce qui a échoué, pourquoi le trafic normal s’est arrêté, où le trafic est allé ensuite, ce que cela a coûté, et comment fermer ou annuler la stratégie ?
Si la réponse est non, laissez le disjoncteur en environnement de test. Si la réponse est oui, utilisez l’accès centralisé aux modèles, le routage, la visibilité de l’usage, la facturation et les contrôles de quota de Flatkey dans le cadre de la boucle de révision. Lorsque vous êtes prêt à valider des routes derrière une passerelle compatible OpenAI, obtenez une clé et commencez avec un flux de travail, une route de modèle et une stratégie de disjoncteur.
