Panne d’API LLM : préparer un mode dégradé pour vos agents IA

En cas de panne d’API LLM, un agent IA fiable doit pouvoir ralentir, différer ou interrompre le traitement sans inventer une réponse ni répéter indéfiniment la requête. Pour préparer un mode dégradé, distinguez d’abord une surcharge temporaire d’un quota épuisé, d’une erreur de configuration ou d’une requête invalide. Chaque cas appelle une action différente.

Une indisponibilité peut être partielle : délai dépassé, erreur temporaire ou limite de compte atteinte. La bonne réponse dépend de la tâche et des conséquences d’une reprise tardive ou répétée.

Le mode dégradé n’est donc pas seulement « réessayer ou changer de modèle ». C’est une décision produit et technique préparée à l’avance : dire ce qui s’arrête, ce qui peut attendre et ce qui doit passer à une personne.

Comment distinguer une panne temporaire d’une erreur durable ?

Commencez par classer l’erreur à partir du statut, du code fournisseur et du contexte de la requête. Un 429 peut signaler une limite de débit, mais aussi un quota ou un plafond de dépenses atteint. Répéter immédiatement le même appel ne résout pas ces causes. Des erreurs serveur ou de surcharge peuvent être temporaires, sans garantir que la tentative suivante réussira.

OpenAI documente un 503 de service surchargé; Anthropic distingue 529 overloaded_error, 504 timeout_error et 500 api_error; Gemini Developer API cite 429 RESOURCE_EXHAUSTED et 503 UNAVAILABLE parmi les erreurs parfois temporaires. Consultez les codes d’erreur OpenAI et les erreurs de l’API Anthropic. Vérifiez la documentation du SDK utilisé et ne transposez pas les codes d’un fournisseur à l’autre.

Classez les erreurs : transitoire, limite ou quota, authentification ou configuration, requête refusée, résultat incertain après timeout. Une clé invalide appelle une correction, pas une boucle de tentatives. Un quota atteint exige une intervention ou une réduction d’usage.

Quand faut-il réessayer un appel au modèle ?

Réessayez seulement quand la cause semble temporaire et que l’opération peut encore être utile. Si une réponse fournit un délai de reprise, respectez-le. Sinon, prévoyez un backoff progressif avec une part d’aléatoire et un nombre de tentatives limité. La documentation OpenAI recommande des reprises bornées et un backoff avec jitter pour certaines erreurs de limite ou de surcharge. Anthropic indique que ses SDK officiels réessaient certaines erreurs transitoires, mais le comportement et la configuration varient selon le SDK. Ne supposez pas que le même mécanisme s’applique partout.

Fixez un délai maximal par appel, un nombre de tentatives et une durée totale acceptable. Pour un copilote IA interactif, un message clair peut être préférable à une longue attente. Un travail différable peut être placé en file, avec expiration et état consultable.

Vérifiez si le SDK effectue déjà des tentatives automatiques : des reprises empilées peuvent saturer un service dégradé. La limite doit s’appliquer au parcours complet, pas à chaque couche isolément.

Un timeout ne prouve pas que le fournisseur n’a pas traité la requête. La réponse peut s’être perdue après exécution. Avant de relancer une opération qui modifie un CRM, envoie un message ou déclenche une action métier, prévoyez une clé d’idempotence quand l’API le permet, ou une logique de déduplication côté application. Ne supposez pas que tous les fournisseurs ou tous les outils offrent cette garantie.

Que doit faire l’agent pendant l’indisponibilité ?

Définissez un comportement par fonction, plutôt qu’un fallback général pour tout l’agent. Une recherche documentaire peut parfois être mise en attente; une demande urgente peut être transférée; une action engageante peut devoir s’arrêter jusqu’à validation humaine. Le parcours doit préserver l’état utile de la demande et expliquer à l’utilisateur ce qui se passe, sans présenter une réponse partielle comme complète.

Pour chaque fonction, écrivez une règle de décision courte :

• Continuer en mode limité si une étape non essentielle peut être omise sans changer le sens de la réponse; indiquez clairement la limite.
• Mettre en attente si le travail peut être repris plus tard et si l’utilisateur peut consulter son statut.
• Transférer à une personne si le délai compte ou si le contexte ne permet pas une réponse fiable.
• Arrêter proprement si la réponse du modèle est nécessaire à une action sensible ou si l’état de l’opération est incertain.

Un agent IA de support peut conserver une demande après l’échec du LLM, mais ne devrait ni présenter les extraits du RAG comme une réponse complète, ni lancer une action dans l’outil de support. Une demande de remboursement attend une vérification humaine.

Un agent construit avec OpenAI Agents SDK ou LangGraph peut structurer les étapes, les appels d’outils et la reprise de son exécution. Ces frameworks ne déterminent pas à eux seuls la politique produit à appliquer. Claude, Gemini et Mistral sont des modèles ou fournisseurs à évaluer dans le contexte précis de votre tâche; leurs sorties, capacités et paramètres ne sont pas interchangeables par principe. Notre comparatif des API de modèles donne une grille de choix, tandis que cet article porte sur la conduite à tenir quand un appel échoue.

Une bascule vers un autre fournisseur est-elle sans risque ?

Non : une bascule n’est sûre que si le fournisseur secondaire a été testé sur le même parcours et si l’application sait interpréter sa réponse. Même avec une API proche, les noms de modèles, formats structurés, appels d’outils, limites de contexte et comportements d’erreur peuvent différer. Une réponse produite par le modèle de secours doit repasser les contrôles métier prévus, au lieu d’être acceptée simplement parce qu’elle est arrivée.

Avant d’activer un fallback, vérifiez au minimum :

1. que les données envoyées au fournisseur alternatif sont autorisées par vos règles de confidentialité et votre contrat;
2. que le modèle secondaire peut produire le format attendu et utiliser les outils nécessaires;
3. que la réponse reste dans les limites de qualité définies pour le cas d’usage;
4. que les quotas et la capacité du fournisseur alternatif sont suffisants pour absorber la charge déplacée;
5. que l’utilisateur ou l’équipe peut savoir quel parcours a été utilisé et pourquoi.

Un fallback peut déplacer la surcharge vers la seconde API ou rejouer des appels en double. Un coupe-circuit peut suspendre les appels vers une dépendance défaillante, puis permettre une reprise progressive; ce choix doit être testé. Pour l’IA souveraine ou des données sensibles, vérifiez aussi les règles de traitement et de résidence avant tout transfert.

Comment tester et surveiller le mode dégradé ?

Simulez les réponses lentes, erreurs temporaires, limites, échecs d’authentification et succès tardifs après expiration du délai. Vérifiez que l’application borne les retries, conserve le contexte, évite les doublons et informe l’utilisateur, y compris si le fournisseur a traité une requête dont la réponse s’est perdue.

Langfuse suit les traces d’un agent; OpenTelemetry instrumente services et dépendances; GitHub Actions exécute les tests à chaque modification. Promptfoo compare des prompts ou modèles sur un jeu de cas, mais ne remplace pas les tests d’erreur réseau. Choisissez l’outil selon ce que vous devez observer et définir vous-même les seuils et données conservées.

Suivez erreurs par fournisseur et fonction, latence, tentatives, tâches en attente et transferts humains. Les traces d’un agent en production aident à reconstituer un incident; les SLO et alertes d’un service IA indiquent quand agir.

Préparez la reprise avant la prochaine panne

Consignez pour chaque erreur connue sa cause probable, l’action permise, le délai, le nombre maximal de tentatives et le message utilisateur. Testez le scénario, notamment après un changement de modèle, de SDK ou de fournisseur.

Un mode dégradé ne promet pas une réponse permanente : il borne les reprises, met en attente ou transfère quand c’est préférable, et s’arrête si l’état est incertain. Pour intégrer ces tests aux evals, à la CI/CD, à l’observabilité et aux garde-fous d’un agent en production, consultez notre méthode.