Intégration sûre d'API tierces : réessais, timeouts, circuit breakers

Pourquoi les API tierces peuvent bloquer vos workflows centraux

Une API tierce peut échouer de manières qui ne ressemblent pas à un arrêt net. Le problème le plus courant, c'est la lenteur : les requêtes restent en attente, les réponses arrivent en retard et votre appli attend. Si ces appels sont dans le chemin critique, un petit incident externe s'accumule à l'intérieur de votre système.

C'est ainsi qu'un ralentissement local devient une panne complète. Les threads ou workers restent bloqués en attente, les files d'attente gonflent, les transactions de base de données restent ouvertes plus longtemps et de nouvelles requêtes commencent à expirer. Rapidement, même des pages qui n'utilisent pas l'API externe semblent cassées parce que le système est surchargé par du travail en attente.

L'impact est concret. Un fournisseur d'identité instable bloque les inscriptions et les connexions. Un timeout sur une passerelle de paiement fige le paiement et laisse les utilisateurs incertains quant à la facturation. Un retard de messagerie bloque les réinitialisations de mot de passe et les confirmations de commande, ce qui déclenche une deuxième vague de réessais et de tickets support.

L'objectif est simple : isoler les échecs externes pour que les workflows centraux continuent de tourner. Cela peut vouloir dire laisser un utilisateur passer une commande et confirmer le paiement plus tard, ou accepter une inscription même si l'email de bienvenue échoue.

Un bon indicateur de réussite : quand un fournisseur est lent ou en panne, votre appli doit quand même répondre rapidement et clairement, et la portée du problème doit rester limitée. Par exemple, la plupart des requêtes principales terminent toujours dans votre budget de latence normal, les échecs restent confinés aux fonctionnalités qui dépendent réellement de cette API, les utilisateurs voient un statut clair (en file, en attente, réessayer plus tard) et la récupération se fait automatiquement quand le fournisseur revient.

Les modes d'échec à prévoir

La plupart des échecs sont prévisibles, même si leur timing ne l'est pas. Nommez-les à l'avance et vous pouvez décider quoi réessayer, quoi arrêter et quoi afficher à l'utilisateur.

Les catégories courantes :

• Pics de latence (des requêtes qui prennent soudainement 10x plus de temps)
• Erreurs transitoires serveur ou réseau (timeouts, 502/503, réinitialisations de connexion)
• Limitations de débit et épuisement de quotas (429s, plafonds journaliers)
• Problèmes d'authentification et de permissions (clés expirées, accès révoqué)
• Données erronées ou surprenantes (champs manquants, mauvais formats, réponses partielles)

Tous les erreurs ne se valent pas. Les problèmes transitoires valent souvent la peine d'être réessayés car un nouvel appel peut réussir (petits défauts réseau, timeouts, 502/503 et certains 429 après attente). Les problèmes permanents ne se corrigent généralement pas tout seuls (identifiants invalides, endpoints erronés, requêtes mal formées, refus de permission).

Traiter toutes les erreurs de la même façon transforme un petit incident en indisponibilité. Réessayer des échecs permanents gaspille du temps, épuise plus vite les quotas et crée un arriéré qui ralentit tout le reste. Ne jamais réessayer des échecs transitoires oblige les utilisateurs à répéter des actions et perd du travail qui aurait pu aboutir quelques instants plus tard.

Accordez une attention particulière aux workflows où une pause ressemble à une rupture : paiement, connexion, réinitialisation de mot de passe et notifications (email/SMS/push). Un pic de deux secondes sur une API marketing est ennuyeux. Un pic de deux secondes sur l'autorisation de paiement bloque les revenus.

Une question utile : "Cet appel est-il requis pour terminer la tâche principale de l'utilisateur maintenant ?" Si oui, il faut des timeouts serrés, des réessais prudents et un chemin d'échec clair. Si non, déplacez-le dans une file et gardez l'appli réactive.

Timeouts : choisissez une limite et tenez-vous-y

Un timeout est le temps maximum que vous êtes prêt à attendre avant d'abandonner et d'avancer. Sans limite claire, un fournisseur lent peut accumuler des requêtes en attente et bloquer le travail important.

Il est utile de séparer deux types d'attente :

• Connect timeout : combien de temps vous essayez d'établir la connexion.
• Read timeout : combien de temps vous attendez la réponse après connexion.

Choisir des valeurs n'est pas une question de perfection. Il s'agit d'adapter l'attente à la patience humaine et à votre workflow.

• Si un utilisateur regarde un spinner, vous avez généralement besoin d'une réponse rapide et d'une étape suivante claire.
• Si c'est un job en arrière-plan (synchronisation nocturne des factures), vous pouvez donner plus de temps, mais il doit quand même y avoir un plafond pour éviter un blocage infini.

Une manière pratique de choisir les timeouts est de partir de l'expérience :

• Combien de temps un utilisateur peut-il attendre avant que vous deviez afficher un message clair ?
• Si cet appel échoue maintenant, pouvez-vous le réessayer plus tard ou utiliser un repli ?
• Combien d'appels de ce type sont lancés à la charge maximale ?

Le compromis est réel. Trop long et vous bloquez des threads, workers et connexions DB. Trop court et vous provoquez des faux échecs et des réessais inutiles.

Des réessais qui n'aggravent pas les pannes

Les réessais aident quand un échec est probablement temporaire : un bref problème réseau, un pépin DNS ou un 500/502/503 ponctuel. Dans ces cas, une seconde tentative peut réussir et l'utilisateur ne remarquera rien.

Le risque, c'est une tempête de réessais. Quand de nombreux clients échouent en même temps et réessaient ensemble, ils peuvent surcharger le fournisseur (et vos propres workers). Le backoff et le jitter évitent cela.

Un budget de réessai vous garde raisonnable. Limitez les tentatives et plafonnez le temps total pour que les workflows centraux ne restent pas bloqués à cause d'un tiers.

Une recette par défaut sûre pour les réessais

• Réessayez seulement quelques fois (souvent 1 à 3 tentatives au total, selon le flux).
• Utilisez un backoff exponentiel (par exemple 200ms, 500ms, 1s) plus un jitter aléatoire.
• Plafonnez le temps total passé en réessais (souvent quelques secondes pour les flux orientés utilisateur).
• Utilisez un timeout par tentative plutôt qu'un seul long timeout pour toutes les tentatives.

Ne réessayez pas les erreurs clients prévisibles comme 400/422 (validation), 401/403 (auth) ou 404. Elles échoueront presque toujours encore et ne feront qu'ajouter de la charge.

Une autre garde-fou : ne réessayez les opérations d'écriture (POST/PUT) que si vous avez mis en place l'idempotence, sinon vous risquez des doubles facturations ou des enregistrements dupliqués.

Idempotence : rendez les réessais sûrs pour des workflows réels

L'idempotence signifie que vous pouvez exécuter la même requête plusieurs fois et obtenir le même résultat final. C'est important parce que les réessais sont normaux : les réseaux lâchent, les serveurs redémarrent et les clients expirent. Sans idempotence, un réessai « utile » crée des doublons et de vrais problèmes financiers.

Imaginez un paiement : l'API est lente, votre appli timeoute et vous réessayez. Si le premier appel a en réalité réussi, le réessai peut provoquer une seconde facturation. Le même risque existe pour la création d'une commande, le démarrage d'un abonnement, l'envoi d'un email/SMS, l'émission d'un remboursement ou la création d'un ticket support.

La solution est d'attacher une clé d'idempotence (ou un ID de requête) à chaque appel « faire quelque chose ». Elle doit être unique par action utilisateur, pas par tentative. Le fournisseur (ou votre service) utilise cette clé pour détecter les duplicatas et renvoyer le même résultat au lieu de répéter l'action.

Traitez la clé d'idempotence comme une partie du modèle de données, pas comme un header qu'on espère ne pas oublier.

Un pattern qui tient en production

Générez une clé quand l'utilisateur commence l'action (par exemple quand il clique sur Payer), puis stockez-la avec votre enregistrement local.

À chaque tentative :

• Envoyez la même clé.
• Stockez le résultat final reçu (réponse de succès, code d'échec, ID de paiement).
• Si vous avez déjà un résultat enregistré, renvoyez ce résultat au lieu de répéter l'action.

Si vous êtes le « fournisseur » pour des appels internes, appliquez le même comportement côté serveur.

Circuit breakers : arrêter d'appeler l'API quand elle échoue

Un circuit breaker est un interrupteur de sécurité. Quand un service externe commence à échouer, vous cessez de l'appeler pendant une courte période au lieu d'ajouter encore des requêtes qui vont probablement expirer.

Les circuit breakers ont généralement trois états :

• Fermé : les requêtes passent normalement.
• Ouvert : les appels sont bloqués pendant une fenêtre de refroidissement.
• Semi-ouvert : après la période, un petit nombre d'appels de test vérifie si le service est revenu.

Quand le breaker est ouvert, votre appli doit faire quelque chose de prévisible. Si une API de validation d'adresse est en panne lors d'une inscription, acceptez l'adresse et marquez-la pour révision ultérieure. Si une vérification de risque de paiement est indisponible, placez la commande en revue manuelle ou désactivez temporairement l'option en l'expliquant.

Choisissez des seuils qui correspondent à l'impact utilisateur :

• erreurs consécutives (par exemple 5 échecs d'affilée)
• taux d'échec élevé sur une courte fenêtre
• nombreuses réponses lentes (timeouts)
• codes d'état spécifiques (503 répétés)

Gardez les fenêtres de refroidissement courtes (secondes à une minute) et limitez les sondes en mode semi-ouvert. L'objectif est de protéger d'abord les workflows centraux, puis de récupérer rapidement.

Replis et files : gardez l'appli utilisable

Quand une API externe est lente ou en panne, votre objectif est de laisser l'utilisateur avancer. Cela signifie avoir un Plan B honnête sur ce qui s'est passé.

Replis : choisissez une expérience « assez bonne »

Un repli est ce que fait votre appli quand l'API ne répond pas à temps. Les options incluent utiliser des données en cache, passer en mode dégradé (masquer des widgets non essentiels, désactiver des actions optionnelles), demander une saisie utilisateur plutôt que d'appeler l'API (saisie manuelle d'adresse) ou afficher un message clair avec la prochaine étape.

Soyez honnête : ne dites pas qu'une action est terminée si ce n'est pas le cas.

Files : faire plus tard quand « maintenant » n'est pas requis

Si le travail n'a pas besoin d'être terminé pendant la requête utilisateur, poussez-le dans une file et répondez vite. Candidats courants : envoi d'emails, synchronisation vers un CRM, génération de rapports et envoi d'événements analytiques.

Échouez vite pour les actions essentielles. Si une API n'est pas requise pour finaliser le paiement (ou la création de compte), ne bloquez pas la requête. Acceptez la commande, mettez l'appel externe en file et réconciliez plus tard. Si l'API est requise (par exemple autorisation de paiement), échouez rapidement avec un message clair et ne faites pas attendre l'utilisateur.

Ce que l'utilisateur voit doit correspondre à ce qui se passe en coulisses : un statut clair (terminé, en attente, échoué), une promesse que vous pouvez tenir (reçu maintenant, confirmation plus tard), un moyen de réessayer et un enregistrement visible dans l'UI (journal d'activité, badge en attente).

Limites de débit et charge : évitez les pannes auto-infligées

Les limites de débit sont la façon pour un fournisseur de dire : « Vous pouvez nous appeler, mais pas trop souvent. » Vous les atteindrez plus vite que prévu : pics de trafic, jobs en arrière-plan qui se déclenchent en même temps ou un bug qui boucle sur des erreurs.

Commencez par contrôler le nombre de requêtes que vous générez. Regroupez quand c'est possible, mettez en cache les réponses même pour 30 à 60 secondes quand c'est sûr, et limitez le rythme côté client pour ne pas exploser plus vite que ce que le fournisseur accepte.

Quand vous recevez un 429 Too Many Requests, traitez-le comme un signal de ralentir.

• Respectez Retry-After quand il est fourni.
• Ajoutez du jitter pour que plusieurs workers ne réessaient pas exactement au même instant.
• Limitez les réessais pour les 429 afin d'éviter des boucles sans fin.
• Augmentez le backoff en cas de 429 répétés.
• Enregistrez-le comme métrique pour détecter les motifs avant que les utilisateurs ne les remarquent.

Limitez aussi la concurrence. Un seul workflow (par ex. synchronisation des contacts) ne doit pas consommer tous les workers et priver les flux critiques comme la connexion ou le paiement. Des pools séparés ou des plafonds par fonctionnalité aident.

Pas à pas : une recette d'intégration sûre par défaut

Chaque appel tiers a besoin d'un plan d'échec. Vous n'avez pas besoin de perfection. Vous avez besoin d'un comportement prévisible quand le fournisseur a une mauvaise journée.

1) Classifier l'appel (indispensable vs peut-attendre)

Décidez ce qui se passe si l'appel échoue maintenant. Un calcul de taxe pendant le checkout peut être indispensable. La synchronisation d'un contact marketing peut généralement attendre. Ce choix guide le reste.

2) Fixer des timeouts et un budget de réessai

Choisissez des timeouts par type d'appel et appliquez-les de façon cohérente. Ensuite, définissez un budget de réessai pour ne pas continuer à marteler une API lente.

• Indispensable, utilisateur en attente : timeout court, 0–1 réessai.
• Peut-attendre, job en arrière-plan : timeout plus long, quelques réessais avec backoff.
• Ne jamais réessayer indéfiniment : plafonnez le temps total par tâche.

3) Rendre les réessais sûrs avec l'idempotence et le suivi

Si une requête peut créer quelque chose ou facturer de l'argent, ajoutez des clés d'idempotence et stockez un enregistrement de la requête. Si une demande de paiement timeoute, un réessai ne doit pas entraîner une double facturation. Le suivi aide aussi le support à répondre : « Est-ce que c'est passé ? »

4) Ajouter un circuit breaker et un comportement de repli

Quand les erreurs augmentent, arrêtez d'appeler le fournisseur pendant une courte période. Pour les appels indispensables, affichez un chemin "Réessayer" clair. Pour les appels qui peuvent attendre, mettez le travail en file et traitez-le plus tard.

5) Surveiller le minimum

Suivez la latence, le taux d'erreur et les événements d'ouverture/fermeture du breaker. Alertez sur des changements soutenus, pas sur des incidents isolés.

Erreurs courantes qui transforment un petit problème en panne

La plupart des pannes d'API ne commencent pas grandes. Elles le deviennent parce que votre appli réagit de la pire façon : elle attend trop, réessaye trop agressivement et mobilise les mêmes workers qui font tourner le reste.

Ces motifs causent des cascades :

• Réessayer chaque échec, y compris les 4xx comme requêtes invalides, authentification expirée ou permissions manquantes.
• Mettre des timeouts très longs « pour être sûr », ce qui consomme silencieusement des threads, connexions DB ou runners jusqu'à épuisement des capacités.
• Réessayer des opérations de création sans clés d'idempotence, entraînant doubles facturations, expéditions en double ou enregistrements répétés.
• Circuit breakers mal configurés qui ne récupèrent jamais ou s'ouvrent/ferment en oscillation.
• Traiter des pannes partielles comme des pannes totales au lieu de dégrader uniquement la fonctionnalité affectée.

De petites corrections évitent de grosses pannes : ne réessayez que les erreurs probablement transitoires (timeouts, certains 429, certains 5xx) et plafonnez les tentatives avec backoff et jitter ; gardez des timeouts courts et intentionnels ; exigez l'idempotence pour toute opération qui crée ou facture ; et concevez pour des pannes partielles.

Checklist rapide avant mise en production

Avant de déployer une intégration en prod, faites un passage rapide avec un état d'esprit d'échec. Si vous ne pouvez pas répondre "oui" à un point, considérez-le comme un blocage de release pour les workflows centraux comme l'inscription, le checkout ou l'envoi de messages.

• Les limites de temps sont explicites (connect timeout et read/response timeout).
• Les réessais sont limités (petit budget de réessai, backoff, jitter et plafond de temps total).
• Les réessais sont sûrs pour les actions réelles (clés d'idempotence ou vérifications claires de déduplication).
• Il y a un breaker et un plan B (repli, mode dégradé ou file).
• Vous pouvez détecter les problèmes tôt (latence, taux d'erreur et santé des dépendances par fournisseur et endpoint).

Si un fournisseur de paiement commence à timer out, le bon comportement est "le checkout se charge toujours, l'utilisateur voit un message clair et vous n'attendez pas indéfiniment", pas "tout reste bloqué jusqu'à l'expiration".

Exemple : protéger le checkout quand un fournisseur est instable

Imaginez un checkout qui appelle trois services : une API de paiement pour prélever la carte, une API de taxe pour calculer la TVA et une API d'email pour envoyer le reçu.

L'appel de paiement est le seul qui doive être synchrone. Les problèmes de taxe ou d'email ne devraient pas bloquer l'achat.

Quand l'API de taxe est lente

Supposons que l'API taxe prenne parfois 8 à 15 secondes. Si le checkout attend, les utilisateurs abandonnent leur panier et votre appli bloque des workers.

Un flux plus sûr :

• Fixer un timeout strict (par exemple 800ms à 2s) et échouer vite.
• Réessayer au maximum une fois, seulement si c'est sûr, avec du jitter.
• Si le timeout est atteint, utilisez un tarif en cache ou la dernière table connue pour la région de l'acheteur.
• Si vous ne pouvez pas légalement utiliser des tarifs en cache, placez la commande en "taxe en attente" et mettez la recalculation en file.

Résultat : moins de paniers abandonnés et moins de commandes bloquées quand le fournisseur taxe est lent.

Quand l'API d'email est en panne

L'email de reçu compte, mais il ne doit jamais bloquer la capture du paiement. Si l'API d'email échoue, le circuit breaker doit s'ouvrir après quelques échecs rapides et arrêter les appels pendant une courte fenêtre.

Au lieu d'envoyer l'email en ligne, placez un job "envoyer reçu" en file avec une clé d'idempotence (par exemple order_id + email_type). Si le fournisseur est en panne, la file réessaie en arrière-plan et le client voit toujours un achat réussi.

Résultat : moins de tickets support pour des confirmations manquantes et pas de revenus perdus parce que le checkout échoue pour des raisons non liées au paiement.

Prochaines étapes : déployer ça partout de façon sûre

Choisissez un workflow qui vous fait le plus de mal quand il casse (checkout, inscription, facturation) et faites-en votre intégration de référence. Puis copiez les mêmes valeurs par défaut partout.

Un ordre de déploiement simple :

• Définissez des timeouts et échouez vite avec un message clair.
• Ajoutez des réessais avec backoff, mais seulement pour les erreurs réessayables.
• Ajoutez l'idempotence pour que les réessais ne facturent pas deux fois ni ne créent deux fois.
• Ajoutez des circuit breakers pour qu'un fournisseur défaillant ne bloque pas votre workflow central.

Documentez vos valeurs par défaut et tenez-les banales : un connect timeout unique, un request timeout, un nombre max de réessais, une fourchette de backoff, un temps de cooldown pour le breaker et les règles sur ce qui est réessayable.

Faites un exercice d'échec avant d'étendre au workflow suivant. Forcez des timeouts (ou bloquez le fournisseur en environnement de test), puis confirmez que l'utilisateur voit un message utile, que les replis fonctionnent et que les réessais en file ne s'accumulent pas indéfiniment.

Si vous développez rapidement de nouveaux produits, il vaut la peine de transformer ces valeurs de fiabilité en un modèle réutilisable. Pour les équipes utilisant Koder.ai (koder.ai), cela signifie souvent définir une fois les règles de timeout, réessai, idempotence et breaker, puis appliquer le même pattern à travers les nouveaux services au fur et à mesure que vous générez et itérez.