Article

Idempotence : éviter de traiter deux fois la même demande

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.

Fixer une valeur se répète sans dommage, ajouter une valeur non

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.

DemandeAprès une exécutionAprès deux exécutions identiques
Fixer une valeur à 100La valeur vaut 100Elle vaut toujours 100
Ajouter 10 à une valeur initialement à 100La valeur vaut 110Elle vaut 120
Marquer une commande comme payéeLe 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.

Une réponse manquante laisse le client dans l’incertitude

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.

HTTP déclare certaines méthodes idempotentes, mais pas POST

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.

La clé désigne le paiement, pas chaque tentative

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 :

  • La clé est inconnue. Le serveur réserve la demande pour qu’un seul traitement puisse l’exécuter.
  • Le paiement est terminé. Le serveur retrouve le résultat enregistré et le renvoie sans refaire le débit.
  • Le paiement est encore en cours. Le serveur ne lance pas un second débit. Selon le contrat de l’API, il fait attendre le client ou lui indique de réessayer plus tard.
Un paiement de 10 euros portant paiement-7f3a est exécuté, mais sa réponse se perd. Une reprise avec le même contenu et la même clé retrouve le résultat sans second débit, dans les conditions du contrat.
Après un paiement terminé dont la réponse a été perdue, le serveur retrouve le résultat de la même demande. Cette reprise dépend du contenu, du périmètre, de la conservation de la clé et du contrat de bout en bout.

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 protection dépend du contenu, du périmètre et de la durée de conservation

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.

La clé n’ordonne pas les messages

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.

Le paiement repris sans second débit

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.

Sources

Explorer

Sur le même sujet

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.

Laisser un commentaire

Elle n'est jamais affichée ni publiée. Elle sert à regrouper vos commentaires et, si vous vous inscrivez un jour avec elle, à vous les rendre.

Votre commentaire sera relu avant d'être publié.