Article

Idempotence HTTP : quand réessayer PUT, DELETE ou POST ?

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.

Votre client envoie une demande de paiement, puis la connexion se coupe. Il ignore si le serveur a encaissé. Peut-il renvoyer la requête ? La méthode donne une première réponse : HTTP déclare PUT et DELETE idempotents, c’est-à-dire répétables sans effet supplémentaire, mais pas POST, la méthode habituelle d’un paiement. Pour un POST, la décision dépend du contrat de reprise que l’API attache à l’opération, et de ce que le client a observé : une coupure, un refus temporaire, un conflit. Le seul message « erreur réseau » ne suffit pas à décider.

Les sections suivantes accompagnent un paiement fictif, P42, de sa préparation à sa confirmation : ce que promet la méthode, le contrat que l’opération y ajoute, la réponse perdue puis retrouvée, le choix de la tentative suivante selon ce que le client observe, et la couche du système qui conduit ces tentatives.

Ce que la méthode HTTP promet déjà

La RFC 9110, §9.2.2, définit l’idempotence par l’effet demandé : une méthode est idempotente si plusieurs requêtes identiques ont, sur le serveur, le même effet voulu qu’une seule. PUT et DELETE possèdent cette sémantique, ainsi que les méthodes sûres comme GET, qui ne demandent aucun changement. POST ne la possède pas par défaut. La RFC en donne l’usage : 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 promesse porte sur l’effet, pas sur la réponse. Un second DELETE peut répondre autrement que le premier, parce que la ressource a déjà disparu ; l’effet demandé reste le même. Elle ne protège pas non plus d’un changement fait par un autre client entre deux envois : un PUT répété vise le même état, mais il peut écraser une modification concurrente. Les préconditions de version protègent cette autre dimension ; l’idempotence ne les remplace pas.

Pour une méthode non idempotente, la même section demande au client de ne pas répéter automatiquement la requête, sauf s’il sait que sa sémantique est idempotente quelle que soit la méthode, ou s’il peut vérifier que la première n’a jamais été appliquée. Cette exception laisse la place à un contrat propre à l’opération : rien n’interdit au paiement P42 d’en ajouter un.

Le paiement P42 ajoute son propre contrat

Dans cette API fictive, le client enregistre localement, avant tout envoi, la clé P42, le montant de 12 000 centimes, la devise EUR et le bénéficiaire V1. La clé représente un paiement voulu ; chaque tentative de transport conserve cette même identité et les mêmes paramètres.

POST /paiements HTTP/1.1
Host: api.example
Content-Type: application/json
Idempotency-Key: "P42"

{"montant_centimes":12000,"devise":"EUR","beneficiaire":"V1"}

Le contrat du serveur promet que les demandes simultanées qui portent P42 dans le périmètre de ce compte ne créent qu’une opération, que le serveur conserve son résultat pendant la durée annoncée, et qu’il refuse la réutilisation de P42 avec un contenu différent. Ces propriétés sont celles du contrat fictif : le nom de l’en-tête ne les installe pas automatiquement. Le mécanisme de reconnaissance d’une demande répétée, côté serveur, est détaillé dans un autre article.

L’en-tête Idempotency-Key fait l’objet d’un projet IETF, révision 07. À la vérification du 20 octobre 2026, ce projet est expiré et archivé : ce n’est pas une RFC adoptée. Il recommande déjà des règles proches de celles de P42 : une erreur 422 pour une clé réutilisée avec un autre contenu, une erreur 409 pour une tentative arrivée pendant que la première est encore traitée, et une politique d’expiration publiée. Des fournisseurs définissent néanmoins leurs propres garanties ; elles doivent être lues pour l’API utilisée.

La réponse perdue, puis retrouvée

Le serveur crée le paiement T18, mais sa réponse se perd. Le client marque P42 « résultat inconnu » : ni succès, ni échec. S’il dispose d’une consultation par référence client, il l’utilise d’abord, puisqu’elle ne demande pas un nouveau paiement. Dans ce contrat, il peut également renvoyer exactement la requête ci-dessus : le serveur reconnaît P42 et retrouve T18.

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"demande":"P42","paiement":"T18","etat":"confirme"}

Le 200 est un choix de cette API pour un résultat retrouvé ; une autre pourrait restituer la réponse originale. C’est ce que fait la version 1 de l’API de Stripe, qui renvoie le code et le corps enregistrés lors de la première requête, même s’il s’agissait d’une erreur 500. La propriété utile est l’absence d’un second paiement et la possibilité d’identifier le premier. Le client peut maintenant informer l’utilisateur de T18.

Si le budget de tentatives est épuisé, le client interrompt la reprise et conserve P42 pour un rapprochement ultérieur. Il ne passe pas à une clé P43 pour contourner l’erreur : une nouvelle clé désigne une nouvelle demande, et le serveur pourrait créer un second paiement. Si la durée de conservation annoncée par le serveur est dépassée, renvoyer P42 peut ne plus être sûr, puisque le serveur a pu oublier la clé et traiter la requête comme neuve. Le contrat doit alors prévoir un moyen de recherche ou une intervention, plutôt qu’une supposition. Une recherche qui ne retrouve rien n’autorise pas pour autant une clé P43 : tant que la première tentative peut encore aboutir, le résultat reste incertain, et seul un échec définitif permet de recommencer.

La tentative suivante dépend de ce que le client observe

Une réponse perdue n’est qu’une des observations possibles, et les codes de statut en décrivent d’autres. 503 Service Unavailable signale un serveur temporairement incapable de traiter la requête, par exemple à cause d’une surcharge ou d’une maintenance ; il peut s’accompagner d’un en-tête Retry-After, qui suggère combien de temps attendre (RFC 9110, §15.6.4 et §10.2.3). 429 Too Many Requests signale que le client a envoyé trop de requêtes dans un délai donné, et peut aussi porter Retry-After (RFC 6585, §4). 412 signale qu’une précondition envoyée par le client s’est révélée fausse, et un conflit métier signale un état de la ressource incompatible avec la demande. Pour P42, le client réagit ainsi :

ObservationAction du client
Connexion perdue après envoiConserver l’état inconnu ; consulter ou reprendre sous la même identité si le contrat le permet
503 avec attente suggéréeVérifier la rejouabilité, puis attendre dans le budget restant
429Vérifier la rejouabilité ; respecter la politique de limitation et l’éventuel délai ; éviter les appels parallèles de contournement
412 ou conflit métierRelire et réexaminer ; aucune répétition aveugle
Paramètres invalidesCorriger la demande ; déterminer si la correction constitue une nouvelle intention selon le contrat

La dernière ligne dépend du contrat. Celui de P42 refuse la réutilisation de la clé avec un autre contenu : renvoyer P42 avec un montant corrigé n’est possible que si le contrat précise qu’une demande refusée comme invalide n’a pas été enregistrée. C’est le cas dans la version 1 de l’API de Stripe, où une requête dont les paramètres échouent à la validation n’est pas enregistrée et peut être renvoyée. Si la correction change ce que l’utilisateur a voulu payer, elle forme une nouvelle demande, avec une nouvelle clé.

Pour P42, le client prévoit un envoi et une seule reprise automatique, dans un budget de dix secondes, après une attente courte qui comporte une part de variation aléatoire, pour que des clients interrompus au même moment ne reviennent pas tous ensemble. Si cette reprise échoue aussi, le client cesse de réessayer seul : la RFC 9110 recommande de ne pas répéter automatiquement une reprise automatique qui a échoué (§9.2.2). Il consulte alors P42 ou le garde pour un rapprochement. Ces réglages sont illustratifs. Si un Retry-After demande trente secondes, le client n’annonce pas un succès au bout de dix : il remet la reprise à plus tard ou signale l’attente. Le budget borne ce que le client tente automatiquement ; il ne dit rien du paiement, qui a peut-être eu lieu.

Une seule couche conduit la reprise

Entre le client applicatif et le serveur, d’autres composants peuvent renvoyer une requête : une bibliothèque HTTP, une passerelle, un proxy. La RFC 9110 interdit à un proxy de répéter automatiquement une requête non idempotente (§9.2.2). La passerelle de l’exemple transmet la requête sans rejouer les POST. Le client applicatif connaît P42, ses paramètres et sa durée de validité : c’est lui qui conduit la reprise. Si trois couches faisaient chacune trois tentatives, une seule demande pourrait produire jusqu’à 3 × 3 × 3 = 27 envois au serveur, bien au-delà du budget annoncé.

Une politique de proxy doit être vérifiée route par route : la présence de l’en-tête Idempotency-Key ne suffit pas à rendre tout POST rejouable, puisque la garantie vient du contrat de chaque opération.

Tester la reprise sur le nombre de paiements

Le test décisif perd la réponse après la création de T18, puis observe la reprise, le journal des tentatives et le nombre réel de paiements. Vérifier seulement que le client a reçu un 200 manquerait l’effet que la reprise devait protéger : le 200 dit que la dernière tentative a abouti ; il ne dit pas combien de paiements existent.

Pour P42, le client a gardé la même clé et les mêmes paramètres d’une tentative à l’autre, a consulté ou renvoyé la requête dans son budget, et a retrouvé T18 sans créer de second paiement. La méthode POST ne lui promettait rien de tel : c’est le contrat de l’opération qui a rendu la reprise sûre. Réservez donc la reprise automatique d’un POST aux opérations dont le contrat décrit cette reconnaissance, et confiez-la à la seule couche qui connaît la demande.

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é.