Résumé

  • Le projet HTTPAPI sur Idempotency-Key, désormais expiré, place le cycle de vie des clés et leur éventuelle expiration dans le contrat de la ressource. Stripe et AWS documentent des frontières de rétention différentes ; aucune ne devient une règle universelle du protocole.
  • La mémoire des tentatives et l’autorité de produire un effet devraient avoir des vies distinctes. Une instruction ancienne dont l’issue reste inconnue doit être rapprochée d’un état durable ou suspendue, et non redevenir exécutable simplement parce que sa clé a été effacée.

Une réponse absente ne raconte pas ce qui s’est passé. Le serveur a peut-être refusé la requête avant de commencer, travaille peut-être encore, ou a terminé juste avant que la connexion ne tombe. Le client voit le même silence. Sa prochaine action dépend pourtant de la différence entre ces états.

C’est la raison pratique des mécanismes d’idempotence. Le client donne à une tentative une identité que le service peut reconnaître lors d’une reprise. Dans le périmètre annoncé, cette reconnaissance permet de renvoyer le résultat antérieur plutôt que de provoquer un second effet. Mais l’identité n’a de valeur que tant que le service conserve et interprète les informations qui lui correspondent.

Un processus arrêté pendant plusieurs jours peut revenir avec la même requête et la même clé. Entre-temps, le serveur a pu supprimer l’entrée selon sa politique de rétention. Ce qui ressemblait auparavant à une reprise devient alors un premier appel aux yeux du mécanisme. L’intention du client n’a pas forcément changé. C’est la mémoire du service qui a changé.

Le projet draft-ietf-httpapi-idempotency-key-header-07, publié le 15 octobre 2025, expose utilement cette frontière. Il propose une valeur de chaîne dans un champ structuré, une règle d’unicité, une empreinte facultative de la requête et des traitements distincts pour les doublons achevés et concurrents. Il attribue à la ressource le cycle de vie de la clé et la publication de sa politique d’expiration.

Ce document n’est cependant plus actif. La révision 07 a expiré le 18 avril 2026 et Datatracker la présente comme un Internet-Draft HTTPAPI archivé. Son origine dans un groupe de travail ne signifie ni publication comme RFC ni approbation consensuelle comme norme. L’article examine une proposition et des contrats opérationnels actuels, sans leur donner une autorité générale qu’ils n’ont pas.

La garantie dépend d’un contrat, pas d’un mot

Le RFC 9110 définit l’idempotence d’une méthode par son effet voulu lorsqu’elle est répétée. Il n’exige pas que chaque réponse ou chaque ligne de journal soit identique. Il ne promet pas non plus une exécution exactement une fois à travers une chaîne de systèmes. POST et PATCH ne reçoivent pas magiquement cette propriété parce qu’un client ajoute un identifiant aléatoire.

Le projet HTTPAPI rappelle qu’un client généraliste ne peut pas supposer qu’un serveur inconnu respectera la clé. La ressource doit préciser le périmètre d’unicité, les données qui rendent deux requêtes équivalentes, le comportement pendant une exécution en cours et la durée de reconnaissance. « Reprise sûre » est une propriété de cet ensemble, non une qualité intrinsèque du champ d’en-tête.

Même un contrat valable laisse plusieurs formes d’incertitude. Une erreur peut avoir précédé tout travail, survenir après une mutation locale ou masquer une réussite en aval. Une réponse d’erreur mémorisée n’est pas toujours une invitation à recommencer avec une autre clé. Une opération concurrente n’est pas une preuve que la première a échoué. Le traitement proposé des doublons distingue précisément ces situations.

Après achèvement, la ressource devrait restituer le résultat déjà produit, succès ou erreur. Pendant l’exécution, elle devrait signaler un conflit. Une même clé accompagnée d’une autre charge utile pose un problème d’identité. Ces cas ne sont pas trois variantes du même bouton « réessayer » ; ils appellent une résolution différente.

La rétention borne la promesse

Il n’est pas réaliste de conserver sans fin tous les corps de réponse et toutes les clés. Le coût, la confidentialité, les collisions et la durée de vie des ressources doivent être pris en compte. Mais la suppression d’une entrée devient un choix de sûreté dès lors qu’une file de travail peut la rejouer plus tard.

Stripe décrit un exemple concret dans sa documentation actuelle. Le premier code d’état et le premier corps sont enregistrés une fois l’exécution du point d’accès commencée, y compris un résultat d’erreur. Une validation échouée ou un conflit concurrent avant cette exécution ne crée pas ce résultat mémorisé. La documentation permet de supprimer les clés lorsqu’elles ont au moins 24 heures et indique qu’une clé réutilisée après suppression engendre une nouvelle requête.

Ce n’est ni une expiration exacte à 24 heures pour toute clé, ni une règle générale de HTTP, ni la preuve d’un incident de paiement. C’est une frontière propre à ce service. Un client dont la reprise après sinistre peut dépasser cette fenêtre doit prévoir une autre manière de retrouver l’opération, au lieu d’étendre mentalement la garantie.

AWS décrit dans Builders Library un autre cas : une reprise peut arriver après qu’un second acteur a supprimé la ressource créée. L’exemple EC2 conserve un résultat sémantiquement équivalent plutôt que de recréer la ressource. Le texte relie la rétention à la vie de la ressource, augmentée d’un intervalle pour les arrivées tardives, et souligne que les exigences varient selon les services.

Les deux exemples justifient une comparaison de contrats, pas l’invention d’un TTL commun. Un SDK qui réessaie au bout de quelques secondes, un équipement longtemps déconnecté et une restauration de sauvegarde n’ont pas le même horizon. Le décalage entre horizon de reprise et horizon de reconnaissance ne se résout pas avec davantage de temporisation.

Quatre identités à ne pas confondre

La clé de déduplication identifie une tentative dans un périmètre. L’identité de l’opération désigne une instruction métier autorisée. L’identité de l’effet désigne ce qui a effectivement été créé ou modifié. Une intention nouvelle autorise, éventuellement, un autre effet. Ces quatre éléments peuvent être reliés sans être assimilés.

Une nouvelle clé ne prouve pas une nouvelle intention. Une ancienne clé après effacement ne prouve pas que l’instruction précédente n’a jamais abouti. Une ressource supprimée ne prouve pas qu’elle n’a jamais existé. À l’inverse, une charge utile identique peut correspondre à une seconde décision parfaitement légitime. Le contrôle doit porter sur l’intention et l’état, pas seulement sur la similitude des octets.

Un enregistrement durable et compact de l’opération peut maintenir cette distinction au-delà du cache ordinaire. Il peut conserver le périmètre du demandeur, l’instruction autorisée, un engagement sur les paramètres, l’heure d’acceptation, l’état terminal et une référence à l’effet. Il n’a pas besoin de recopier éternellement toute la charge sensible ni toutes les réponses.

L’accès, la durée et l’usage de ce registre doivent être justifiés. Une meilleure reprise ne confère pas un droit à la rétention illimitée. La proposition de gouvernance est simplement de ne pas laisser disparaître simultanément la reconnaissance et le seul moyen de connaître l’issue. Elle n’ajoute pas un champ obligatoire au projet IETF.

L’après-échéance mérite un comportement explicite

Une politique d’expiration devrait indiquer son point de départ, son périmètre, le traitement des erreurs achevées et des travaux encore en cours. Elle devrait aussi dire ce qu’un appel tardif peut obtenir : un refus, une consultation d’état, un rapprochement ou une mise en attente examinable.

Au-delà de la fenêtre, une tentative ancienne et incertaine ne devrait pas devenir silencieusement une instruction neuve. Le client peut arrêter la remise automatique, consulter l’identité connue de l’opération ou de la ressource et demander une décision. Le service peut résoudre l’état dans un registre adapté. Si un autre effet est vraiment voulu, cette intention doit être exprimée comme telle, sans être dissimulée dans une reprise de récupération.

Cela n’interdit pas à un fournisseur de traiter une réutilisation après purge comme un nouvel appel. Cela impose au flux client de ne plus prétendre bénéficier de la garantie précédente. Le contrat technique peut avoir changé de régime ; l’interface et l’autorité doivent le rendre visible.

Le même contrôle concerne les reprises humaines. Un agent de support qui relance un travail trois jours après un incident ne se trouve pas forcément dans le même contrat qu’un SDK qui réessaie après quelques secondes. Générer une nouvelle clé pour faire disparaître un conflit peut améliorer le traitement du ticket tout en transformant une issue inconnue en second effet.

Vérifier l’accord entre mémoire et conséquence

Si le service enregistre la clé sans produire la ressource, il peut prétendre à tort que le travail est terminé. S’il produit la ressource sans enregistrer la clé, il peut recommencer. Le récit AWS insiste sur une coordination atomique entre l’identification et les mutations concernées.

Mais une transaction locale ne couvre pas nécessairement tous les effets en aval. Un système peut avoir validé sa ligne alors qu’un autre a exécuté une instruction dont l’accusé s’est perdu. L’état terminal doit être rattaché à la source qui fait autorité pour chaque conséquence. « Terminé dans la première base » n’est pas une preuve de terminaison de toute la chaîne.

Les essais devraient inclure une reprise après expiration, une suppression de ressource, une charge modifiée, un changement de périmètre du demandeur et une réussite partielle en aval. Le résultat attendu n’est pas seulement un code d’erreur propre. C’est l’absence de second effet non autorisé, accompagnée d’une description honnête de ce qui reste inconnu.

Une file restaurée, un équipement reconnecté ou un export utilisé par le support peut réveiller des instructions anciennes. Ces chemins appartiennent au fonctionnement normal de la récupération. Les ignorer transforme une politique de rétention raisonnable en défaut de coordination.

Sources

  1. Fiche actuelle du projet expiré
  2. Historique du projet
  3. Révision 07 en HTML
  4. Révision 07 en texte
  5. Source XML de la révision 07
  6. Charte de HTTPAPI
  7. Documents de HTTPAPI
  8. Dépôt officiel du projet
  9. Discussion des problèmes du projet
  10. RFC 9110 : sémantique HTTP
  11. RFC 9457 : description des erreurs d’API
  12. RFC 8941 : champs structurés HTTP
  13. RFC 9562 : identifiants UUID
  14. RFC 9111 : mise en cache HTTP
  15. Stripe : requêtes idempotentes
  16. Stripe : traitement des erreurs de bas niveau
  17. AWS : reprises sûres et API idempotentes
  18. AWS : délais, reprises et temporisation
  19. Lu Heng : spécification initiale minimale et décision locale
  20. Lu Heng : le miroir de la politique