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.
Article
Retard des données, service indisponible : quand servir une copie, refuser ou différer une demande ? Un exemple d’API explique les réponses HTTP.
Le service de stock d’une boutique en ligne ne répond plus. L’API de la boutique peut encore afficher sa copie du catalogue, mais peut-elle confirmer qu’un produit est disponible, ou accepter une réservation ? La réponse dépend de ce que chaque opération promet au client. Une consultation peut servir une copie datée ; une réservation qui exige un stock confirmé doit être refusée, ou acceptée pour plus tard sans être annoncée comme réussie. Dans tous les cas, un mode dégradé utile précise ce qui est connu, ce qui reste incertain et ce que le client peut faire ensuite.
Une boutique fictive traverse une panne de son service de stock : la consultation du catalogue, une réservation refusée, puis une réservation acceptée pour plus tard jusqu’à son refus final, et enfin une réponse perdue.
Dans cette boutique, l’API publique répond aux clients. Pour afficher le catalogue, elle lit une copie des données que le service de stock lui transmet au fil des changements. Pour réserver, elle doit interroger ce service, qui tient le stock qui fait foi. Ce matin, le service de stock ne répond plus aux appels de l’API. L’API ne sait pas pourquoi : un service arrêté, une liaison coupée et une réponse très lente se ressemblent de son côté. À la fin de son délai d’attente, elle doit décider sans savoir.
Consulter la fiche d’un produit et réserver son dernier exemplaire ne demandent pas les mêmes garanties. Une copie un peu ancienne peut suffire à la première opération. Elle ne permet pas de garantir la seconde, puisqu’un autre client a peut-être réservé ce dernier exemplaire juste avant la panne.
Le théorème CAP formalise ce choix. Il porte sur une donnée dont plusieurs machines gardent une copie, ici le stock. Dans CAP, la cohérence signifie que les opérations se comportent comme si elles portaient sur une seule copie des données : elles prennent place dans un ordre unique, qui respecte l’ordre réel de celles qui ne se chevauchent pas. La disponibilité, au sens de CAP, exige qu’une demande reçue par une machine en état de marche finisse par obtenir une réponse conforme à l’opération demandée. Eric Brewer a formulé la conjecture en 2000 ; Seth Gilbert et Nancy Lynch l’ont démontrée en 2002 pour un réseau asynchrone. Dès que des messages entre les machines peuvent être perdus, il est impossible de réaliser une donnée partagée, lue et écrite par plusieurs machines, qui garantisse à la fois la cohérence et la disponibilité.
Pour l’API, ce choix se pose à la fin du délai d’attente : répondre avec sa copie, au risque d’une information périmée, ou refuser de répondre sur le fond tant que le service de stock reste injoignable. Brewer situe en 2012 l’essentiel de CAP dans ce moment où le programme doit annuler l’opération ou la poursuivre, et précise que le choix peut se faire de nombreuses fois dans un même système, opération par opération. Le théorème ne signifie pas pour autant que tout retard, tout verrou ou toute erreur d’API relève d’une partition : il décrit ce qu’une machine peut promettre quand elle ne peut plus échanger avec les autres copies d’une donnée.
Pour la fiche d’un produit, l’API répond avec sa copie. Un catalogue mis à jour il y a trente secondes peut rester utile, à condition que le client puisse juger cette fraîcheur quand elle influence sa décision. La réponse indique donc jusqu’à quel instant le stock affiché est connu :
GET /produits/P7 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{"id":"P7","stock_indicatif":1,
"stock_mis_a_jour":"2026-10-01T09:59:30Z"}
L’en-tête HTTP Age (RFC 9111, §5.1) ne suffit pas à dire cette fraîcheur. Il donne l’estimation, par un cache, du temps écoulé depuis que la réponse a été produite ou validée par le serveur d’origine. Il ne mesure pas le retard des données métier : une réponse produite à l’instant peut contenir une copie ancienne. D’où un champ explicite, une date d’actualisation ou une version de la copie, dont le nom précise ce qui a été mis à jour : ici le stock, pas toute la fiche. Dans ce contrat fictif, stock_mis_a_jour dit que la copie contient tous les changements du stock jusqu’à cet instant, sans trou ; la date du dernier changement reçu ne dirait pas la même chose, puisqu’un stock peut rester inchangé longtemps et un changement arriver en retard.
Les caches HTTP connaissent aussi la directive stale-if-error (RFC 5861, §4), qui permet de servir une réponse périmée quand le serveur rencontre une erreur, celles qui produiraient un 500, 502, 503 ou 504, dans la durée de péremption qu’elle autorise au-delà de la fraîcheur normale. Elle ne doit pas servir à contourner une exigence de fraîcheur définie pour l’opération : une réponse en cache qui affiche « en stock » n’en devient pas une confirmation.
Une cliente demande à réserver le dernier exemplaire. L’API demande d’abord au service de stock s’il en reste un, une lecture sans effet, et n’obtient aucune réponse dans son délai. Sans cette réponse, elle ne peut pas garantir l’exemplaire, et la boutique n’a prévu aucun moyen de conserver la demande pour la traiter plus tard. L’API refuse donc avec 503 Service Unavailable, avant d’envoyer la moindre commande de réservation au stock : le serveur est temporairement incapable de traiter la demande. Comme aucune commande n’est partie, la réservation n’a pas eu lieu, et la cliente le sait. Si la commande avait déjà été transmise au stock, son silence laisserait au contraire le résultat inconnu : le stock a pu réserver puis perdre sa réponse, et le 503 n’y changerait rien. Ce cas relève de la réponse perdue, traitée plus bas.
Le statut choisi doit correspondre à ce que le serveur a constaté. Le tableau distingue les codes voisins, avec un exemple de chacun dans la boutique :
| Statut | Situation décrite | Exemple dans la boutique |
|---|---|---|
503 Service Unavailable | Le service est temporairement incapable de traiter la demande, notamment en cas de surcharge ou de maintenance. | L’API ne peut pas traiter la réservation pendant la panne du stock. |
504 Gateway Timeout | Une passerelle ou un proxy n’a pas reçu à temps la réponse nécessaire d’un serveur amont. | Une passerelle qui relaie la réservation au service de stock n’obtient pas sa réponse dans le délai. |
502 Bad Gateway | Une passerelle ou un proxy a reçu une réponse invalide d’un serveur amont. | La même passerelle reçoit du service de stock une réponse inutilisable. |
409 Conflict | La demande entre en conflit avec l’état courant de la ressource. | Service revenu, la demande vise un exemplaire qui n’est plus disponible. |
412 Precondition Failed | Une précondition HTTP envoyée par le client n’est pas satisfaite. | La cliente a conditionné sa demande à une version du produit qui a changé. |
Un corps d’erreur structuré, par exemple au format Problem Details (RFC 9457), peut préciser la cause connue et le moyen de reprendre. Il faut éviter d’annoncer une cause certaine lorsque le serveur ne dispose que d’un délai dépassé : un simple timeout ne permet pas d’affirmer que le service de stock est arrêté.
Retry-After (RFC 9110, §10.2.3) peut accompagner le 503 et suggérer une attente : avec ce code, il indique combien de temps le service devrait rester indisponible. Ce délai ne garantit pas que le service sera revenu, et il ne rend pas une opération non idempotente sûre à répéter.
Changeons une seule chose : la boutique peut conserver durablement la demande dans une file, pour la traiter au retour du service de stock. L’API peut alors répondre 202 Accepted (RFC 9110, §15.3.3) : la demande est acceptée pour traitement, mais ce traitement n’est pas terminé, et il peut encore aboutir à un refus. La RFC ajoute que la réponse devrait décrire l’état de la demande et indiquer un moyen de le suivre. Dans cet échange fictif, les chemins, les champs métier et les types de problème appartiennent à l’API d’exemple :
HTTP/1.1 202 Accepted
Content-Type: application/json
Cache-Control: no-store
Location: /demandes/D42
{"id":"D42","etat":"en_attente",
"reservation_confirmee":false,"suivi":"/demandes/D42"}
La cliente sait que sa demande est conservée ; elle ne sait pas encore si un exemplaire lui reviendra, et le champ reservation_confirmee le dit explicitement. Ce contrat ne contourne pas CAP : il propose une autre opération, avec une autre garantie, celle de la prise en charge différée, dont le résultat reste à connaître. Il suppose que la file elle-même soit disponible pour accepter la demande. Et si votre métier exige une confirmation immédiate, une prise en charge différée ne répond pas au même besoin.
Le client mémorise D42 et consulte son suivi au rythme prévu par le contrat. Il ne déduit pas du 202 qu’une place lui appartient. Au retour du service de stock, la demande est examinée, et l’exemplaire a été vendu entre-temps :
GET /demandes/D42 HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{"id":"D42","etat":"refusee",
"motif":"stock_epuise","reservation_confirmee":false}
Le 200 concerne la consultation réussie du suivi, pas une réservation réussie. Cette distinction évite au client de classer toute réponse 2xx comme un succès de sa mission. Si le service n’avait pas pu conserver D42 au départ, il aurait refusé la prise en charge avec un 503 et un problème structuré, sans fabriquer un identifiant de travail durable.
Certains métiers autorisent aussi un service limité pendant une coupure, avec un plafond ou une part du stock réservée à l’avance. Les règles et le risque accepté doivent alors être définis côté serveur.
Dernière complication : la cliente envoie sa demande de réservation, et aucune réponse HTTP exploitable n’arrive. Le résultat est inconnu. La demande a peut-être été enregistrée sous un identifiant que le client n’a jamais reçu, et renvoyer une demande nouvelle pourrait en créer une seconde, donc deux réservations si les deux étaient acceptées. Le client doit pouvoir retrouver sa demande avec une référence qu’il a choisie avant l’envoi, ou la renvoyer avec cette même référence, selon le mécanisme d’idempotence prévu par le contrat. Une reprise avec la même référence peut être sûre, dans les limites de ce contrat ; une nouvelle référence crée une nouvelle demande. Les règles de répétition des requêtes font l’objet d’un article distinct.
Une réponse partielle demande la même précision. Une recherche qui exclut un entrepôt inaccessible doit signaler sa couverture : une liste vide ne prouve pas l’absence de stock partout. Dans un contrat fondé sur Problem Details, le type d’erreur décrit une condition connue, comme « entrepôt non interrogé », et non une cause supposée.
Après le retour du service de stock, l’API rattrape sa copie du catalogue ou réconcilie les états, et les demandes restées en attente, comme D42, sont examinées. Le client doit pouvoir consulter le résultat de chacune. Le tableau reprend ce que la cliente savait à chaque étape :
| Demande du client | Réponse possible | Ce que le client sait |
|---|---|---|
| Consulter le catalogue | 200 OK, avec la date d’actualisation des données | Le catalogue est consultable ; le stock n’est pas confirmé. |
| Réserver pendant la panne, sans file durable | 503 Service Unavailable | La réservation ne peut pas être traitée maintenant. |
| Déposer une demande dans une file durable prévue par le contrat | 202 Accepted, avec une adresse de suivi | La demande est conservée ; la réservation reste à confirmer. |
| Ne pas recevoir la réponse après l’envoi | Aucune réponse HTTP exploitable | Le résultat est inconnu : vérifier le suivi ou utiliser le mécanisme d’idempotence prévu avant un nouvel envoi. |
Testez la coupure, le retour du service et une réponse perdue après réussite, et vérifiez qu’une demande renvoyée avec la même référence ne crée pas de seconde réservation.
Pour chaque opération, précisez dans le contrat la garantie de fraîcheur attendue et le moyen de connaître le résultat après une réponse perdue. Si le système ne peut pas tenir cette garantie pendant la panne, l’API doit refuser l’opération plutôt que renvoyer un succès trompeur. Dans la boutique, la cliente n’a jamais cru tenir un exemplaire qu’elle n’avait pas : la fiche affichait l’heure de son stock, la réservation immédiate a été refusée, et la demande D42 s’est terminée par un refus qu’elle pouvait consulter.
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.
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.
GET sert souvent les vues de lecture, tandis que les écritures demandent une décision métier. REST et CQRS se combinent sans imposer le même découpage.
Versionner une API utilisée par des agents : rendre le contrat identifiable, annoncer le retrait avec Deprecation et Sunset, puis guider la migration.
Laisser un commentaire
Votre commentaire sera relu avant d'être publié.