Timeout, retry, outbox : choisir une protection adaptée à la panne
Un service ralentit ou un message revient en double : timeout, retry, outbox et idempotence répondent à des risques différents. Voici comment les combiner.
Article
Un paiement sans réponse peut avoir réussi. L’idempotence permet de réessayer sans double débit, à condition de reconnaître la demande et garder son résultat.
Vous cliquez sur « Payer », et la page reste en attente. Le paiement a peut-être échoué ; il a peut-être aussi réussi sans que la réponse vous parvienne. Si vous recommencez, votre compte ne doit pas être débité une seconde fois. L’idempotence sert à cela : une opération idempotente peut être répétée sans que son effet sur les données se multiplie. Un débit ne l’est pas par nature, mais une demande de paiement peut le devenir quand le serveur reconnaît qu’une nouvelle tentative porte la même demande, grâce à une clé que le client garde d’un envoi à l’autre.
Un thermostat montre d’abord ce qu’est une opération idempotente ; le retour au paiement explique ensuite pourquoi une réponse manquante oblige à répéter, ce que HTTP promet déjà selon la méthode, comment une clé rend la demande de paiement répétable, et où s’arrête cette protection.
Régler un thermostat sur 20 °C plusieurs fois conserve la même consigne. Lui demander d’augmenter la consigne de 2 °C plusieurs fois l’augmente à chaque demande. La première opération est idempotente : l’exécuter deux fois laisse le même état que l’exécuter une fois. La seconde ne l’est pas.
Les opérations sur des données se rangent de la même façon. Répéter « le statut de la commande est payé » laisse le même statut. Répéter « retirer 10 euros du compte » retire de nouveau de l’argent.
| Demande | Après une exécution | Après deux exécutions identiques |
|---|---|---|
| Fixer une valeur à 100 | La valeur vaut 100 | Elle vaut toujours 100 |
| Ajouter 10 à une valeur initialement à 100 | La valeur vaut 110 | Elle vaut 120 |
| Marquer une commande comme payée | Le statut est « payée » | Le statut reste « payée » |
Pour juger si une opération est idempotente, il faut regarder tous ses effets métier attendus, y compris une notification, pas seulement la valeur enregistrée. Si chaque changement de statut déclenche aussi un courriel, répéter l’enregistrement laisse le même statut mais envoie deux messages. Le traitement qui envoie la notification doit alors reconnaître lui aussi les doublons.
Un paiement traverse trois étapes : le client envoie la demande, le serveur l’exécute, puis il répond. Le client est ici le logiciel qui appelle le serveur, par exemple la page de paiement ouverte dans votre navigateur. Si la connexion se coupe après l’exécution mais avant l’arrivée de la réponse, le client ne reçoit aucune confirmation, et rien ne lui permet de distinguer ce cas d’une demande qui n’est jamais arrivée.
Abandonner peut laisser un achat payé sans suite ; répéter peut débiter une seconde fois. Un système de messages rencontre le même dilemme : si le destinataire a traité un message sans avoir confirmé sa réception, le système le lui remet, et le destinataire le reçoit une seconde fois. Dans les deux cas, la nouvelle tentative peut répéter une opération déjà réussie : elle n’est sans risque que si l’opération supporte la répétition.
Sur le Web, chaque requête porte une méthode : GET pour lire une ressource, PUT pour la remplacer, DELETE pour la supprimer, et POST pour, entre autres usages, créer quelque chose de nouveau, comme un paiement. La RFC 9110 définit comme idempotentes les méthodes PUT, DELETE et les méthodes dites sûres, qui ne demandent aucun changement, dont GET. Sa définition porte sur l’effet voulu : plusieurs requêtes identiques ont sur le serveur le même effet qu’une seule. Le serveur qui expose ces méthodes doit respecter cette sémantique.
La réponse, elle, peut changer. Une première suppression peut réussir, puis une seconde répondre que la ressource n’existe plus : l’effet demandé reste le même, puisque la ressource est supprimée. La RFC précise aussi que la propriété ne couvre que ce que le client a demandé ; le serveur reste libre, par exemple, de journaliser chaque requête séparément.
Cette propriété répond au cas de la réponse manquante. Selon la même section, une requête idempotente peut être répétée automatiquement si la communication échoue avant que le client ait lu la réponse. La RFC demande en revanche au client de ne pas répéter automatiquement une requête dont la méthode n’est pas idempotente, sauf s’il sait que la requête l’est en réalité, quelle que soit sa méthode, ou s’il peut vérifier que la première n’a jamais été appliquée. POST, la méthode habituelle d’un paiement, ne bénéficie pas de la garantie générale. L’API doit donc donner au client un moyen de savoir que sa demande de paiement est répétable : c’est le rôle du contrat particulier de l’opération.
Un retrait de 10 euros n’est pas idempotent, mais la demande peut le devenir si elle change de forme : au lieu de « retirer 10 euros », le client demande « que le paiement paiement-7f3a, de 10 euros, ait lieu ». Exécutée une première fois, cette demande crée le paiement ; répétée, elle trouve qu’il existe déjà et ne débite rien de plus. Le débit ne devient pas idempotent : le serveur reconnaît que deux messages portent la même demande et n’exécute que le premier. Cette reconnaissance des doublons s’appelle la déduplication.
Pour cela, le client crée un identifiant unique avant le premier envoi et le conserve pour chaque nouvelle tentative. C’est la clé d’idempotence : elle désigne une seule demande de paiement, même si plusieurs messages la transportent. Dans une API HTTP qui prévoit ce mécanisme, elle peut être transmise dans un en-tête :
Idempotency-Key: "paiement-7f3a"
Une nouvelle clé désigne une nouvelle demande. Un client qui fabrique une clé neuve à chaque tentative perd donc toute la protection : le serveur voit deux paiements distincts et peut débiter deux fois.
Cet en-tête fait l’objet d’un projet de spécification à l’IETF. À la vérification du 20 octobre 2026, la révision 07 de ce projet, datée d’octobre 2025, est expirée et archivée : ce n’est pas une RFC publiée. Il décrit une pratique, mais chaque API qui accepte une clé définit ses propres garanties, et le client s’appuie sur le contrat de l’API qu’il utilise.
Le serveur associe la clé à la demande et à son résultat. Son comportement dépend de l’état du premier traitement :
L’arrivée simultanée de deux tentatives demande plus de soin, par exemple quand le client réessaie pendant que le premier traitement tourne encore. Un simple « vérifier que la clé est inconnue, puis débiter » ne suffit pas : les deux traitements peuvent constater en même temps que la clé est inconnue, et débiter tous deux. L’enregistrement de la clé doit empêcher ce cas, par exemple avec une contrainte d’unicité non différée, que la base vérifie au moment de l’insertion, et une transaction adaptée.
Reste la panne entre le débit et l’enregistrement du résultat. Si le paiement passe par un prestataire externe, votre serveur devient à son tour le client de ce prestataire, et la même incertitude se reproduit entre eux. La protection doit donc aller jusqu’au prestataire : votre serveur lui transmet sa propre clé, stable d’une tentative à l’autre, ou peut retrouver chez lui le paiement effectué grâce à une référence connue avant l’envoi. Retrouver le paiement confirme le débit ; ne rien trouver ne prouve pas l’échec, car la première tentative peut encore être en cours ou pas encore visible. Tant qu’elle peut aboutir, le résultat reste incertain et le serveur ne relance pas le débit : seul un échec définitif, qui ne peut plus produire de débit, permet de recommencer. La clé que garde le navigateur ne protège que l’échange entre le navigateur et votre serveur.
La même clé doit toujours désigner la même demande. Si le client la réutilise avec un autre montant ou un autre destinataire, le serveur doit signaler l’incohérence : accepter le nouveau contenu rendrait ambigu ce que la clé désigne. Le serveur fixe aussi le périmètre dans lequel une clé est unique, par exemple un compte client ou une opération : le projet IETF laisse cette définition au propriétaire de la ressource.
Le serveur doit enfin annoncer combien de temps il conserve les clés ; le même projet lui demande de publier sa politique d’expiration. Une fois une clé supprimée, il peut considérer une nouvelle tentative comme une nouvelle demande. Le client ne peut donc pas supposer qu’une clé le protège indéfiniment : une reprise n’est sûre qu’avec la même clé, le même contenu et dans le délai annoncé.
Stripe documente ces règles pour la version 1 de son API. Il compare les paramètres d’une nouvelle tentative à ceux de la requête d’origine et renvoie une erreur s’ils diffèrent. Les clés peuvent être supprimées une fois âgées d’au moins vingt-quatre heures, et une requête qui réutilise une clé supprimée est traitée comme nouvelle. Dès que l’exécution a commencé, Stripe enregistre le code et le corps de la première réponse, et renvoie cette réponse aux tentatives suivantes, même s’il s’agit d’une erreur 500. Ce sont les garanties de cette version de l’API de Stripe, à vérifier séparément chez chaque fournisseur ; Stripe décrit un autre comportement pour la version 2 de son API.
Reconnaître chaque demande ne garantit pas pour autant un résultat juste. Supposons que deux messages demandent successivement de fixer un prix à 100 euros, puis à 120 euros. Chacun est idempotent, et chacun porte sa propre clé. S’ils arrivent dans l’ordre inverse, le prix final devient pourtant 100 euros.
La clé empêche de traiter deux fois le même message ; elle ne rétablit pas l’ordre de messages différents. Un numéro de version, qui fait refuser une modification fondée sur un état dépassé, comme le montre l’article sur les modifications concurrentes, ou un mécanisme d’ordonnancement reste nécessaire lorsque l’ordre change le résultat métier.
Revenons au clic sur « Payer ». La page a créé la clé paiement-7f3a avant le premier envoi. La réponse s’est perdue ; la page renvoie la même requête, avec la même clé et le même montant. Si le premier traitement est terminé, le serveur renvoie le résultat enregistré, et votre compte n’est débité qu’une fois. S’il est encore en cours, le serveur fait patienter la page ou lui demande de revenir plus tard, sans lancer de second débit. Cette reprise est sûre dans les conditions du contrat de l’API : une clé conservée d’un envoi à l’autre, un contenu identique, un délai inférieur à la durée de conservation, et un serveur qui protège aussi son propre appel au prestataire, sans relancer un débit dont le résultat reste incertain.
Testez ces conditions avec des cas qui ressemblent à un incident réel : deux envois simultanés, une réponse perdue, un contenu modifié avec la même clé et une tentative après expiration. Ils révèlent davantage que deux appels bien espacés. Les décisions de reprise du client HTTP, quand réessayer, combien de fois et selon quelle erreur, font l’objet d’un article distinct.
Explorer
Choisis dans l’index d’après les étiquettes de cet article — les plus proches d’abord, hors de sa série. Rien n’est écrit à la main : un article publié demain avec les mêmes étiquettes y prendra place.
Un service ralentit ou un message revient en double : timeout, retry, outbox et idempotence répondent à des risques différents. Voici comment les combiner.
Une réponse HTTP perdue laisse le résultat incertain. Méthodes, clés d’idempotence et suivi du paiement : les conditions pour réessayer sans doublon.
Les études sur les citations par les IA donnent des résultats variables. Comprenez ce qu’elles mesurent avant de transformer leurs observations en recettes.
Laisser un commentaire
Votre commentaire sera relu avant d'être publié.