Relances des API d’IA : récupérer après une panne sans dupliquer les requêtes ni les coûts

Une relance n’est pas une répétition anodine

Relancer un appel consiste à envoyer de nouveau une requête après qu’une tentative précédente n’a pas fourni de réponse exploitable au client. La difficulté tient au fait que « je n’ai pas reçu de réponse » ne signifie pas nécessairement « le serveur n’a pas traité la requête ». La connexion peut être interrompue avant l’envoi, pendant la transmission ou après que le service a reçu et exécuté la requête. Dans ce dernier cas, la renvoyer peut déclencher une seconde opération ou un second coût, même si le client n’a vu qu’une erreur réseau.

Une stratégie pertinente commence donc avant le choix du délai entre les tentatives. Il faut savoir quelle opération est répétée, quel résultat est connu, lequel reste incertain et quel effort supplémentaire est autorisé. Une nouvelle requête sans effet externe et une opération qui lance une tâche, consomme des ressources ou modifie un état ne présentent pas le même risque. Il ne faut pas non plus confondre le rétablissement de la disponibilité avec la garantie qu’une même génération ne sera exécutée qu’une seule fois : cette garantie dépend des capacités documentées de l’API et de la conception de l’intégration.

Ce guide présente des décisions à adapter au fournisseur concerné. La documentation de Kimi et de ShareAI mentionnée ici sert de référence pour leurs API respectives, mais les extraits disponibles ne confirment ni des codes d’erreur précis, ni des en-têtes d’attente, ni des mécanismes d’idempotence. Ces détails ne doivent pas être transposés d’un service à un autre, et il ne faut pas supposer qu’une API les propose sous prétexte qu’ils sont courants ailleurs.

Classez l’échec avant de prendre une décision

Ne regroupez pas toutes les réponses en échec sous une seule règle automatique. Distinguez au minimum les erreurs de configuration ou de validation, les réponses liées aux limites d’utilisation, les délais d’attente dépassés et les problèmes de connexion. Cette classification constitue un point de départ pour l’analyse, pas une table universelle des codes : chaque fournisseur définit ses réponses et leur signification. Consultez la documentation à jour de l’API et consignez les signaux qui justifient une action dans chaque cas.

Une erreur de validation, par exemple, appelle généralement une correction de la requête, pas son renvoi à l’identique. Une limite d’utilisation peut permettre de reprendre plus tard, mais il faut suivre les consignes documentées par le service. Un délai d’attente dépassé ou une déconnexion soulève une autre question : le service a-t-il reçu la requête ? Si cela ne peut pas être déterminé, classez le résultat comme incertain plutôt que de présumer qu’il n’y a pas eu de traitement. Cette distinction compte particulièrement lorsque l’opération peut engendrer des coûts ou des effets répétés.

La décision de relancer doit également tenir compte du caractère apparemment temporaire de l’échec, de l’intérêt de répéter la même requête et du temps ainsi que du nombre de tentatives encore disponibles. La source secondaire consacrée au choix entre relancer une API et changer de modèle recommande de limiter les relances aux échecs transitoires, aux opérations qui peuvent être répétées sans risque et au budget disponible. Il s’agit d’un critère général de conception, pas d’une définition officielle des erreurs d’un fournisseur.

Définissez une stratégie explicite et limitée

Une stratégie de relance doit préciser par écrit quels échecs peuvent déclencher une nouvelle tentative, combien de fois celle-ci est autorisée, quelle peut être la durée totale du cycle et ce que fait le client une fois la limite atteinte. Distinguez l’envoi initial des relances : si vous définissez un nombre maximal de tentatives, indiquez s’il comprend la requête initiale. Cette précision évite les interprétations divergentes entre le code, la configuration et les métriques.

La limite de durée totale — parfois appelée budget temporel — doit englober les délais d’attente et les appels suivants, pas seulement le temps de connexion d’une tentative. Si elle expire, cessez de programmer des répétitions, même si le nombre maximal de tentatives n’a pas été atteint. À l’inverse, atteindre le maximum doit interrompre la séquence, même s’il reste du temps. Cela évite les boucles sans fin et les requêtes qui mobilisent des ressources longtemps après que l’appelant aurait pu utiliser leur résultat.

Il n’existe pas de nombre de tentatives ni de durée adaptés à toutes les API. Justifiez ces paramètres en fonction de la latence tolérée par l’application, des indications du fournisseur, du coût potentiel de l’opération et du comportement mesuré en situation d’échec. Le guide de dépannage de Kimi mentionne une stratégie d’attente exponentielle et le contrôle du nombre de requêtes ; l’extrait disponible ne recommande aucune valeur universelle et ne confirme pas que cette approche s’applique à toutes les erreurs.

Lorsque la documentation d’une API indique un signal d’attente, vérifiez sa signification et sa portée, puis suivez les instructions du fournisseur. N’inventez pas le nom d’un en-tête et n’interprétez pas le signal d’un autre service comme s’il était équivalent. Si aucun signal documenté n’a été vérifié, le client ne doit pas prétendre pouvoir en déduire le bon moment pour reprendre.

Attentes progressives et dispersion aléatoire

Une attente progressive augmente le délai entre des tentatives successives. Elle peut réduire la pression produite par des appels répétés immédiatement lorsqu’un service est saturé ou en panne. La documentation de dépannage de Kimi mentionne l’attente exponentielle ainsi que le contrôle du nombre de requêtes. Cela confirme que ces notions figurent dans la documentation de Kimi ; cela ne définit pas une configuration valable pour d’autres API et ne démontre pas qu’un délai donné convienne à toutes les situations.

La dispersion aléatoire, ou jitter, introduit une variation dans les délais afin que de nombreux clients ayant échoué au même moment ne rappellent pas simultanément. C’est un outil de conception possible, pas une obligation universelle. Évaluez s’il est compatible avec les signaux publiés par le fournisseur et le délai maximal de l’opération. Si une instruction d’attente est documentée, ne la remplacez pas par un délai aléatoire susceptible de la contredire.

Documentez les paramètres retenus et la raison de chacun : évolution des délais, limite supérieure, variation appliquée et arrêt de la séquence à l’expiration du budget. Mesurez les effets à partir des données opérationnelles : nombre de tentatives par requête, succès après relance, durée totale, erreurs finales et consommation associée lorsque celle-ci peut être mesurée. Ne transformez pas une recommandation générale en valeur universelle sans essais auprès du fournisseur et sous une charge représentative.

Évitez les doublons : idempotence et résultats incertains

L’idempotence est une propriété qui permet de répéter une opération sans produire d’effets supplémentaires, dans les conditions définies par le système. Il ne suffit pas de trouver le terme sur une page : vérifiez si le fournisseur propose une clé d’idempotence ou un mécanisme équivalent, quels endpoints ou quelles opérations sont couverts, comment le mécanisme s’utilise, pendant combien de temps il est reconnu et ce qui se passe si la même clé est réutilisée avec des paramètres différents. Seule la documentation actuelle du fournisseur peut confirmer ces garanties.

Les sources disponibles ne vérifient pas la prise en charge de l’idempotence par Kimi ou ShareAI. La page ShareAI indique explicitement que les écritures doivent être traitées avec prudence, mais l’extrait ne confirme aucune clé ni garantie particulière. Il ne faut donc pas affirmer que l’un ou l’autre de ces fournisseurs déduplique les requêtes par défaut. Si l’API ne documente aucun mécanisme applicable, considérez une déconnexion après l’envoi comme un résultat potentiellement incertain et vérifiez les éventuels mécanismes de rapprochement proposés par le fournisseur.

Faites la différence entre consulter de nouveau une opération déjà identifiée et en lancer une nouvelle. Si l’API documente un identifiant permettant de consulter l’opération, utilisez-le uniquement dans les limites et pendant la durée décrites. S’il n’existe aucun moyen documenté de vérifier le résultat, l’intégration doit choisir entre s’arrêter, signaler l’incertitude ou autoriser une répétition en mentionnant explicitement le risque. Ne promettez pas une exécution exactement une fois sans garantie vérifiée qui couvre le cas concerné.

Exemple détaillé : la réponse se perd après l’envoi

Imaginez qu’une application envoie une requête de génération. Le client attend la réponse, mais la connexion est interrompue. Il ignore si le serveur a reçu la requête, s’il a commencé à la traiter ou s’il l’a terminée. Au lieu de la renvoyer automatiquement, il marque la tentative comme incertaine et consulte la documentation de cette API : existe-t-il une clé d’idempotence applicable ? Un moyen documenté de vérifier l’état ? Une stratégie définie par le fournisseur pour ce type d’interruption ? La réponse détermine l’étape suivante.

Si un mécanisme documenté couvre cette opération, l’intégration peut relancer ou consulter l’état en respectant exactement sa portée. Sinon, elle ne peut pas déduire d’une erreur de transport que le service n’a pas traité la requête. L’équipe doit appliquer la stratégie de risque approuvée à l’avance : par exemple, s’arrêter et afficher un état en attente de vérification, ou autoriser une répétition en précisant qu’elle peut entraîner une consommation supplémentaire. Le choix approprié dépend des conséquences d’une opération en double et des mécanismes disponibles ; il n’existe pas de réponse universelle.

Si le fournisseur renvoie une réponse définitive, le cycle s’arrête conformément à la signification documentée de cette réponse. En cas de succès, aucune nouvelle tentative n’est programmée. Si un échec temporaire est confirmé et que la répétition est sûre, vérifiez de nouveau les limites, le budget et le délai d’attente. Si le budget expire ou si le nombre maximal de tentatives est atteint, arrêtez la séquence et consignez le résultat final ou incertain. Le compteur ne doit jamais être réinitialisé simplement parce qu’un autre processus prend en charge la requête.

Testez des échecs réalistes avant le déploiement

Les tests doivent vérifier aussi bien la décision de relancer que celle de s’arrêter. Simulez un échec que la configuration classe comme temporaire et vérifiez que le client respecte la limite. Simulez des échecs persistants et confirmez que les répétitions ne se poursuivent pas indéfiniment. Faites expirer le budget temporel alors qu’il reste encore des tentatives possibles ; vérifiez ensuite que l’atteinte du nombre maximal interrompt également le cycle, même s’il reste du temps.

Ajoutez une réponse tardive et une déconnexion immédiatement après l’envoi. Ce sont deux cas distincts : une réponse tardive peut arriver alors que le client considère déjà son délai d’attente comme dépassé, tandis qu’une déconnexion après l’envoi laisse incertain l’état du traitement. Vérifiez que l’application ne duplique pas une opération en supposant que ces deux situations signifient « le serveur n’a rien fait ». Si le fournisseur propose une fonction d’idempotence, les tests doivent confirmer sa portée dans un environnement approprié et à partir de la documentation à jour, plutôt que de simuler une garantie que le service n’a pas promise.

Ajoutez des cas d’erreur de validation et de limite d’utilisation afin de vérifier qu’une règle générale n’est pas appliquée à toutes les réponses. Si le fournisseur publie des signaux d’attente, testez leur interprétation conformément à la documentation. Enfin, vérifiez que les journaux permettent de reconstituer l’ordre des tentatives sans enregistrer inutilement les prompts, les réponses ou des données sensibles. Les identifiants de corrélation, le type de résultat, les délais et le numéro de tentative sont souvent plus utiles au diagnostic que la copie de l’intégralité de la requête.

Critères de mise en production

Avant le déploiement, consignez la documentation consultée, la date de sa vérification et la version ou l’endpoint auquel elle s’applique. Distinguez les consignes du fournisseur des décisions propres à l’application : une recommandation documentée ne remplace pas l’analyse du risque de doublon, et une stratégie locale ne doit pas être présentée comme une garantie du service.

Examinez les résultats après le déploiement. Une hausse du nombre de tentatives par appel, des cycles arrivés à leur terme ou des résultats incertains peut signaler une dégradation, une configuration trop agressive ou une évolution du comportement du service. Traitez le fallback — par exemple, une autre route approuvée — comme une décision différente de la relance : la source secondaire sur les API de LLM recommande de ne basculer que vers une solution de remplacement approuvée à l’avance. Vérifiez la compatibilité, la qualité, la confidentialité et les coûts avant d’activer un fallback ; ne l’utilisez pas pour masquer le fait que l’appel initial a peut-être déjà été traité.

Enfin, mesurez séparément la récupération technique et la qualité de la réponse. Le fait qu’un appel aboutisse après plusieurs tentatives ne prouve pas que le contenu généré est correct ou adapté. Une stratégie robuste limite les risques et clarifie les résultats ; elle ne remplace ni l’évaluation de la sortie du modèle ni les décisions de sécurité de l’application.

Poursuivre l’exploration

Corrections et transparence

Si vous repérez une information incorrecte ou obsolète, envoyez-nous la page et la source à vérifier.