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

Vous cliquez sur « Payer », mais 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. Réessayer ne doit pas débiter votre compte une seconde fois. L'idempotence sert à cela : répéter une même opération sans multiplier son effet sur les données.

Fixer une valeur et ajouter une valeur ne se répètent pas de la même façon

Régler un thermostat sur 20 °C plusieurs fois conserve la même consigne. Lui demander d'augmenter de 2 °C plusieurs fois augmente la température à chaque demande. La première opération est idempotente, la seconde ne l'est pas.

En informatique, la distinction est la même. 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.

Il faut regarder l'effet complet de l'opération. Si chaque changement de statut déclenche aussi un courriel, répéter l'enregistrement peut laisser le même statut tout en envoyant deux messages. Le traitement de notification doit lui aussi prévoir les doublons.

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

Un paiement traverse plusieurs étapes : le client envoie la demande, le serveur l'exécute, puis le serveur répond. Une coupure après l'exécution mais avant la réception de la réponse laisse le client sans confirmation.

La nouvelle tentative peut alors répéter une opération déjà réussie. Un système de messages peut rencontrer le même problème : si le destinataire a traité le message mais n'a pas confirmé sa réception, le système le lui remet.

Pat Helland décrit ce rôle de l'idempotence dans les systèmes distribués. Prévoir les doublons permet de relancer un traitement après un incident sans demander au client de deviner ce qui s'est passé.

La clé identifie le paiement, pas chaque tentative

Pour protéger un débit, le client crée un identifiant unique avant le premier envoi. Il conserve cet identifiant lorsqu'il réessaie. 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 sous cette forme :

Idempotency-Key: paiement-7f3a

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.

La vérification de la clé doit résister à deux arrivées simultanées. Un simple « vérifier, puis débiter » ne suffit pas si deux traitements peuvent tous deux constater que la clé est inconnue. L'enregistrement doit empêcher ce cas, par exemple avec une contrainte d'unicité et une transaction adaptée.

Autre point à prévoir : une panne entre le débit et l'enregistrement du résultat. Si le paiement passe par un prestataire externe, la protection doit aller jusqu'à ce prestataire ou permettre de retrouver le paiement effectué. Une clé enregistrée uniquement dans le navigateur ne donne pas cette garantie.

La protection dépend aussi du contenu 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 le résultat ambigu.

Le serveur doit aussi annoncer combien de temps il conserve les clés. 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é protège indéfiniment.

Stripe documente ces règles pour son API : comparaison des paramètres, conservation d'au moins vingt-quatre heures avant suppression possible, puis nouveau traitement si une clé supprimée est réutilisée. Ce sont les garanties de cette API, à vérifier séparément chez chaque fournisseur.

Je conseille de tester les 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.

HTTP donne des garanties différentes selon la méthode

La RFC 9110 définit comme idempotentes les méthodes PUT, DELETE et les méthodes dites sûres, dont GET. Le serveur doit respecter cette sémantique. POST ne bénéficie pas de cette garantie générale.

Une opération POST peut néanmoins proposer une clé d'idempotence, comme les paiements évoqués ici. Le client s'appuie alors sur le contrat particulier de l'API. Le document IETF consacré à cet en-tête décrit cette pratique ; il faut distinguer un projet de spécification d'une norme publiée.

Une réponse HTTP identique n'est pas nécessaire pour qu'une méthode soit idempotente. 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 : la ressource est supprimée.

Les doublons et l'ordre des messages sont deux problèmes distincts

Supposons que deux messages demandent successivement de fixer un prix à 100 euros puis à 120 euros. Chacun peut être idempotent. 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 leur ordre. Un numéro de version ou un mécanisme d'ordonnancement reste nécessaire lorsque l'ordre change le résultat métier.

Sources

• RFC 9110, HTTP Semantics, §9.2.2 Idempotent Methods, juin 2022.
• IETF, The Idempotency-Key HTTP Header Field.
• Stripe, Idempotent requests.
• P. Helland, Idempotence Is Not a Medical Condition, ACM Queue, 2012.