Introduction : un clic, deux commandes et un tunnel où les réponses se perdent

Imaginez une intégration qui tourne depuis des années. Votre service envoie des commandes vers un système externe, le flux passe par un pool de proxies mobiles pour répartir les requêtes par région et éviter de saturer les limites d'une seule adresse. Tout est stable. Et soudain, la comptabilité apporte un rapport : sur le mois, le partenaire a vu apparaître quarante-sept commandes jumelles. Mêmes produits, mêmes montants, trois à quatre secondes d'écart à la création. Personne n'a rien changé. Que s'est-il passé ?

Il s'est passé la chose la plus banale du monde : la connexion via le proxy s'est coupée au retour. Le serveur a reçu la requête, créé la commande, envoyé la réponse, mais la réponse n'est jamais arrivée au client. Le client a honnêtement conclu que la requête avait échoué, et l'a répétée. La deuxième requête s'est exécutée elle aussi. C'est ainsi que naît un doublon, et aucune politique de reprise ne protège à elle seule contre ça.

Il faut tout de suite tracer une frontière. Nous avons déjà consacré un article à la bonne manière de réessayer après une erreur 429, au temps d'attente entre les tentatives et à la construction d'un backoff exponentiel : c'est le sujet de la politique de reprise. Aujourd'hui, le propos est autre. Nous parlons du contrat entre le client et le serveur qui rend une reprise sûre ou dangereuse, indépendamment de la façon dont vous l'exécutez. Ce contrat s'appelle l'idempotence, et son outil principal est la clé d'idempotence.

Pourquoi le sujet est-il particulièrement sensible quand on passe par un proxy ? Parce que le proxy ajoute un maillon supplémentaire où la réponse peut se perdre. Les proxies mobiles, en plus, changent l'IP externe lors de la rotation, et le serveur peut très bien voir la seconde requête arriver d'une autre adresse. Si votre protection anti-doublon s'appuie sur la session, l'IP ou une fenêtre temporelle, elle s'effondre. Si elle s'appuie sur une clé d'idempotence, peu lui importe d'où vient la reprise.

Dans ce guide, vous allez découvrir comment fonctionne l'idempotence au niveau du protocole et de la logique métier, comment générer et stocker les clés, comment concevoir un stockage serveur capable d'encaisser des reprises concurrentes, que faire quand une API externe ne supporte pas les clés, et sur quelles erreurs même des équipes expérimentées trébuchent. Nous allons dérouler des cas chiffrés, dresser des check-lists et répondre aux questions gênantes. Le contenu s'adresse aux développeurs d'intégrations, aux architectes et aux tech leads qui travaillent sur des commandes, des paiements et toute opération où « deux fois » veut dire « mauvaise nouvelle ».

Les bases : qu'est-ce que l'idempotence et pourquoi une répétition de requête est-elle dangereuse ?

Définition simple

Une opération est idempotente si son exécution répétée produit le même résultat qu'une exécution unique. Appuyer dix fois sur le bouton d'appel de l'ascenseur est idempotent : l'ascenseur viendra une fois. Ajouter une unité de plus au panier n'est pas idempotent : chaque clic modifie l'état. Virer de l'argent n'est certainement pas idempotent, sauf si le système est spécialement conçu pour qu'une répétition du virement avec le même identifiant ne fasse rien.

En HTTP, certains méthodes sont considérées comme idempotentes par la spécification : GET, PUT, DELETE, HEAD. Il y a la méthode POST, qui par défaut n'est pas considérée comme idempotente. Or c'est justement POST qu'on utilise le plus souvent pour créer des commandes, des paiements, envoyer des messages. Autrement dit, l'opération la plus risquée vit dans la méthode la moins idempotente. Coïncidence ? Plutôt une régularité historique avec laquelle il faut composer.

Trois issues possibles pour toute requête

Quand le client envoie une requête et ne reçoit pas de réponse, il se retrouve dans l'incertitude. Il y a exactement trois scénarios :

  • La requête n'a pas atteint le serveur. On peut réessayer sans risque : rien ne s'est produit.
  • La requête a atteint le serveur, l'opération a été exécutée, la réponse s'est perdue. Réessayer est dangereux : l'opération s'exécutera une seconde fois.
  • La requête a atteint le serveur, l'opération a commencé mais n'est pas terminée. Réessayer est doublement dangereux : deux opérations vont s'exécuter en parallèle.

Le hic, c'est que le client ne peut pas distinguer ces scénarios. Un timeout ressemble à la même chose dans les trois cas. Une connexion coupée aussi. D'où un principe fondamental des systèmes distribués : une livraison fiable ne peut être qu'« au moins une fois » (at-least-once). La garantie « exactement une fois » (exactly-once) est impossible à obtenir au niveau du transport ; on peut seulement l'émuler au niveau applicatif en rendant les reprises inoffensives. L'idempotence est précisément ce moyen d'émulation.

Comment le proxy allonge la chaîne d'incertitude

Sans proxy, il n'y a qu'un segment réseau entre le client et le serveur. Avec un proxy, il y en a deux : client — proxy et proxy — serveur. La réponse peut se perdre sur l'un ou l'autre. Et si elle se perd sur le premier segment, le proxy a déjà reçu la réponse, le serveur a déjà terminé l'opération, et le client ne le saura jamais.

Les proxies mobiles ajoutent leur spécificité. Ils font tourner l'IP selon un planning ou à la demande, basculent entre stations de base, subissent les fluctuations naturelles de la qualité radio. Chacun de ces événements peut rompre la connexion TCP à un moment arbitraire. Et le plus souvent, la coupure ne survient pas pendant l'envoi du corps de la requête (il est petit et part vite), mais pendant l'attente de la réponse, quand la connexion reste simplement ouverte. C'est précisément à ce moment-là que le serveur traite votre commande. C'est précisément à ce moment-là qu'une coupure offre le maximum de chances de doublon.

Qu'est-ce qu'une clé d'idempotence ?

Une clé d'idempotence (Idempotency-Key) est un identifiant unique d'opération métier, que le client génère une seule fois et transmet avec chaque tentative d'exécution de cette opération. Le serveur mémorise la clé et le résultat. Si une requête revient avec la même clé, le serveur ne réexécute pas l'opération : il renvoie le résultat enregistré. Le client peut réessayer autant qu'il veut : la commande ne sera créée qu'une fois.

Notez bien la formulation : la clé identifie une opération, pas une requête HTTP. Cette distinction deviendra centrale plus loin, quand nous examinerons les erreurs d'implémentation.

Plongée en profondeur : le contrat serveur et l'anatomie d'une reprise sûre

Le contrat comme accord de comportement

L'idempotence n'est ni un en-tête ni une bibliothèque. C'est un contrat où le serveur promet au client un comportement précis en cas de reprise, et où le client promet de respecter les règles de génération des clés. Un bon contrat répond aux questions suivantes :

  1. Quelle entité constitue l'unité d'idempotence : la commande, le paiement, la ligne de commande, le lot ?
  2. Comment le client transmet-il la clé : en-tête, champ du corps, élément de l'URL ?
  3. Que se passe-t-il si la clé correspond mais que le corps de la requête diffère ?
  4. Que se passe-t-il si la première requête est encore en cours quand une seconde arrive avec la même clé ?
  5. Combien de temps le serveur conserve-t-il la clé ?
  6. Que renvoie-t-on lors d'une reprise : exactement la même réponse au byte près, ou l'état actuel de l'entité ?
  7. Comment distingue-t-on une reprise d'une nouvelle requête dans les logs et les métriques ?

Si ne serait-ce qu'une de ces questions n'a pas de réponse dans la documentation de l'API, le contrat est incomplet, et dans les situations indéterminées le comportement dépendra de l'implémentation, de la version et de la phase de la lune.

Les trois états d'une clé

Côté serveur, chaque clé a un cycle de vie en trois états. Comprendre ce cycle explique quatre-vingt-dix pour cent des problèmes de doublons.

  • Absente. La clé est vue pour la première fois. Le serveur doit la réserver de façon atomique et démarrer le traitement.
  • En cours (in-progress). La première requête est en traitement. Une seconde requête avec la même clé ne doit pas lancer un second traitement. Options : renvoyer 409 Conflict en invitant à patienter, se bloquer jusqu'à la fin de la première et renvoyer son résultat, renvoyer 202 Accepted avec un lien de statut.
  • Terminée. Le résultat est enregistré. La reprise renvoie le résultat enregistré sans effet de bord.

L'erreur d'architecture la plus fréquente est d'omettre l'état intermédiaire. Le développeur vérifie « la clé est-elle en base », ne la trouve pas, commence le traitement, et une reprise parallèle fait exactement la même chose au même instant. Deux threads, deux vérifications, deux commandes. La vérification et la réservation doivent être une seule opération atomique : insertion avec index unique, écriture conditionnelle dans Redis, transaction avec verrou.

L'empreinte de la requête

La clé identifie une opération, mais une opération avec quel contenu ? Si le client, à cause d'un bug, a envoyé la clé K avec un montant de 1000 euros, puis a réessayé avec la même clé et un montant de 10000, que doit faire le serveur ? Renvoyer silencieusement le résultat de la première opération est dangereux : le client croira avoir payé 10000. Exécuter la seconde revient à violer l'idempotence.

La bonne réponse : le serveur stocke une empreinte (fingerprint) de la requête — un hash du corps normalisé et des en-têtes significatifs. En cas de reprise avec la même clé mais une empreinte différente, on renvoie une erreur 422 Unprocessable Content ou 400 avec un code explicite du type idempotency_key_reused_with_different_payload. Cela protège à la fois des erreurs logiques du client et des reprises falsifiées.

Stockage de la réponse : snapshot ou état actuel

Deux approches existent pour ce qu'on renvoie lors d'une reprise. Le snapshot : le serveur conserve le statut, les en-têtes et le corps de la réponse d'origine et les renvoie tels quels. C'est strictement idempotent et prévisible. L'état actuel : le serveur retrouve l'entité créée par la clé et renvoie sa représentation actuelle. C'est plus pratique si la commande a changé de statut entre les tentatives, mais moins prévisible.

Dans les systèmes de paiement, le snapshot domine : le client doit recevoir exactement la réponse de la première tentative. Dans les systèmes de gestion de commandes, on utilise souvent un hybride : snapshot pour les codes d'erreur, état actuel pour le succès. L'essentiel est que le choix soit figé dans le contrat.

Ce que le proxy change au niveau du contrat

Techniquement, le proxy ne participe pas au contrat d'idempotence : il est transparent pour les en-têtes et le corps. Mais il change les probabilités. En connexion directe, perdre une réponse alors que l'opération a réussi est une rareté, une fraction de pour cent d'une fraction de pour cent. À travers une chaîne avec proxy mobile et rotation, cet événement devient régulier. Nous avons observé des intégrations où, avec une rotation d'IP toutes les cinq minutes, environ 0,3 à 0,8 % des requêtes se terminaient par une coupure de connexion pendant l'attente de la réponse. À dix mille commandes par jour, cela fait trente à quatre-vingts doublons potentiels quotidiens. Sans clé d'idempotence, chacun devient un vrai doublon.

Il y a une seconde subtilité. Beaucoup de serveurs intègrent dans leur anti-fraude une vérification du type « requête répétée depuis une autre IP ». Avec la rotation du proxy mobile, la reprise arrivera presque toujours d'une nouvelle adresse. Si le serveur l'interprète comme une activité suspecte et rejette la reprise sans consulter le stockage des clés, le client n'obtiendra pas le résultat enregistré et restera dans l'incertitude. Un bon contrat vérifie la clé avant toute heuristique liée au réseau.

Méthode 1 : génération et transmission de la clé d'idempotence côté client

Où naît la clé

Règle d'or : la clé est générée une seule fois par opération métier, avant la première tentative d'envoi, et conservée avec l'intention d'exécuter l'opération. Si la clé est créée à l'intérieur du client HTTP à chaque appel, la reprise obtiendra une nouvelle clé et toute la protection s'annule. C'est une erreur si fréquente que nous la traiterons à part dans la section des anti-patterns, mais répétons-le ici : la clé vit au niveau du service de commandes, pas au niveau du transport.

La séquence pratique est la suivante :

  1. L'utilisateur ou un processus interne initie la création d'une commande.
  2. Le service crée un enregistrement local « intention de commande » avec le statut pending et génère la clé.
  3. La clé et la charge utile sont enregistrées dans la base locale dans une même transaction.
  4. Ce n'est qu'après le commit de la transaction que l'envoi vers l'API externe via le proxy est lancé.
  5. Toutes les reprises lisent la clé dans l'enregistrement local, elles n'en génèrent pas de nouvelle.
  6. Après réception de la réponse, l'enregistrement local est mis à jour avec le résultat et l'identifiant externe de la commande.

Cet ordre garantit que même un redémarrage de votre service au milieu des reprises ne changera pas la clé : elle est en base.

Format de la clé

La clé doit être globalement unique et imprévisible pour des tiers. Options qui fonctionnent :

  • UUID version 4 — le classique, 122 bits d'aléa, utilisable partout.
  • UUID version 7 ou ULID — ils contiennent un horodatage dans les bits de poids fort, ce qui les rend pratiques à trier et à indexer dans la base du serveur. En 2026, c'est déjà le choix standard pour les nouveaux systèmes.
  • Clé déterministe dérivée d'un identifiant naturel — par exemple un hash de l'identifiant du panier, de l'identifiant utilisateur et de la version du panier. Utile quand le client peut lui-même perdre son état et régénérer la clé à partir des mêmes données.

À éviter : les nombres séquentiels (faciles à deviner pour obtenir la réponse d'autrui), les chaînes courtes, les clés dépendant uniquement d'un horodatage de faible précision.

Mode de transmission

Le standard de fait est l'en-tête Idempotency-Key. Le brouillon de spécification IETF consacre précisément ce nom, et la plupart des API modernes s'y tiennent. Exemple d'appel via proxy :

curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders

Certaines API acceptent la clé dans le corps de la requête (champ client_reference_id, external_id, request_id). C'est aussi une option valable, avec une nuance : si le serveur utilise un champ du corps comme clé, ce champ doit impérativement figurer dans l'index unique, sinon ce n'est qu'une étiquette, pas une protection.

Portée de la clé

La clé doit être unique au sein d'un même compte client et d'un même point de terminaison. Un bon serveur compose sa clé de stockage interne comme la combinaison de l'identifiant de compte, de la méthode, du chemin et de la clé transmise. Cela protège des collisions entre clients et de la réutilisation accidentelle d'une clé pour une autre opération.

Check-list côté client

  • La clé est générée avant la première tentative et stockée en base avec l'intention.
  • Toutes les reprises utilisent la même clé.
  • Le corps de la requête lors d'une reprise est identique au byte près à la première tentative.
  • Le client sait interpréter un 409 (opération en cours) comme un signal d'attente et de reprise, et non comme une erreur.
  • Le client sait interpréter un 422 avec un code de non-concordance d'empreinte comme une erreur logique nécessitant une intervention.
  • Le client journalise la clé dans toutes les entrées liées à l'opération, pour pouvoir enquêter en cas de doublon.
  • Le client ne réinitialise pas la clé lors d'un changement de proxy, d'une rotation d'IP ou d'un basculement vers un pool de secours.

Méthode 2 : implémentation serveur du stockage des clés

Si vous possédez le serveur que vos clients ou partenaires appellent via proxy, cette section vous concerne. Si vous n'êtes que client, elle vous aidera à évaluer la qualité d'une implémentation tierce à partir de sa documentation et de son comportement.

Schéma de stockage

La table ou la structure minimale pour les clés contient les champs suivants :

  • scope_key — clé composite : compte, méthode, chemin, Idempotency-Key transmise. Index unique.
  • fingerprint — hash du corps de requête normalisé.
  • state — l'une des valeurs : in_progress, completed, failed.
  • response_status, response_headers, response_body — snapshot de la réponse, rempli à la fin.
  • resource_id — identifiant de l'entité créée, si applicable.
  • locked_at, completed_at, expires_at — horodatages pour traiter les opérations bloquées et purger.

Réservation atomique

Le cœur de l'implémentation est l'opération qui, en une seule action, soit crée un enregistrement à l'état in_progress, soit signale que l'enregistrement existe déjà. Dans une base relationnelle, c'est une insertion avec gestion du conflit sur index unique. Dans Redis, c'est une commande SET avec les options NX et EX, qui n'écrit la valeur qu'en l'absence de clé et fixe immédiatement le TTL. Pas de « d'abord SELECT, puis INSERT » : entre les deux, une reprise parallèle se glissera.

Pseudo-code au niveau logique :

  1. Calculer scope_key et fingerprint.
  2. Tenter d'insérer un enregistrement avec state = in_progress. Si l'insertion réussit, passer à l'exécution de l'opération.
  3. En cas de conflit : lire l'enregistrement existant.
  4. Si le fingerprint ne correspond pas — renvoyer 422 avec un code de non-concordance.
  5. Si state = in_progress — renvoyer 409 avec un en-tête Retry-After, ou attendre la fin (dans une limite raisonnable).
  6. Si state = completed — renvoyer le snapshot de réponse enregistré avec un en-tête marquant la reprise, par exemple Idempotent-Replayed: true.

Exécution et fixation du résultat

C'est là que se cache le second piège. L'opération s'est exécutée, la commande est créée, mais le processus tombe avant d'écrire le résultat dans le stockage des clés. L'enregistrement reste à l'état in_progress pour toujours. La reprise reçoit 409, puis encore 409, et ainsi de suite à l'infini.

Trois approches pour résoudre cela :

  • Transaction unique. La création de la commande et la mise à jour de l'enregistrement de clé s'exécutent dans une même transaction de base de données. La variante la plus fiable si la commande et les clés vivent dans la même base.
  • La clé comme partie de l'entité. La clé d'idempotence est stockée directement dans la table des commandes avec un index unique. La commande elle-même est alors l'enregistrement de clé ; une table séparée n'est pas nécessaire. Simple et robuste pour les cas à une seule entité par opération.
  • Récupération des opérations bloquées. Un processus d'arrière-plan trouve les enregistrements in_progress plus anciens qu'un seuil (par exemple 60 secondes), vérifie si l'opération a effectivement été exécutée (via resource_id ou par recherche d'entité), puis soit achève la fixation, soit passe l'enregistrement en failed pour autoriser la reprise.

Gestion des erreurs de la première tentative

Que conserver si la première tentative se termine par une erreur ? Cela dépend du type d'erreur. Les erreurs de validation (400, 422) sont déterministes : une reprise avec le même corps donnera le même résultat, on peut les mettre en cache. Les erreurs d'infrastructure (500, 503, timeout de base) ne sont pas déterministes : si on les met en cache, le client ne pourra jamais exécuter l'opération avec succès. Le bon comportement : en cas d'erreur d'infrastructure, libérer la clé (supprimer l'enregistrement ou le passer en failed avec possibilité de reprise) pour que la prochaine reprise réessaie.

Durée de vie de la clé

Les clés ne peuvent pas être conservées éternellement : la table enflera. Mais un TTL trop court est dangereux : si le client réessaie une demi-heure après une panne réseau, la clé doit être vivante. La pratique des grands prestataires de paiement converge vers 24 heures comme minimum. Pour le e-commerce, 24 à 72 heures sont raisonnables. Pour les opérations que le client peut répéter après de longues pannes (par exemple une synchronisation de catalogue quotidienne), le TTL doit dépasser au moins du double l'intervalle de synchronisation.

Observabilité

Chaque reprise doit laisser une trace. Les métriques à collecter : nombre de reprises tombant sur completed (reprises inoffensives), nombre de 409 (reprises concurrentes), nombre de 422 (non-concordance d'empreinte — presque toujours un bug client), âge du plus ancien enregistrement in_progress (indicateur d'opérations bloquées). Le ratio entre reprises et opérations uniques est une mesure directe de la qualité du réseau entre client et serveur. S'il grimpe brutalement, la qualité du canal proxy s'est dégradée ou la rotation a changé.

Check-list côté serveur

  • La réservation de la clé est atomique.
  • Il existe un état in_progress distinct et une réponse claire à une reprise concurrente.
  • L'empreinte du corps est stockée, la non-concordance est rejetée par une erreur explicite.
  • La fixation du résultat est transactionnelle, ou un mécanisme de récupération des enregistrements bloqués existe.
  • Les erreurs d'infrastructure ne sont pas mises en cache, les déterministes le sont.
  • Le TTL n'est pas inférieur à 24 heures et il est documenté.
  • La reprise est marquée par un en-tête et visible dans les métriques.
  • La vérification de la clé a lieu avant les heuristiques réseau de l'anti-fraude.

Méthode 3 : un protocole de reprise via proxy qui ne casse pas l'idempotence

La politique de reprise est le sujet d'un article voisin, mais il existe une zone étroite où politique de reprise et idempotence se croisent : quels signaux de la chaîne proxy signifient qu'une reprise est nécessaire, et comment une reprise ne doit pas casser le contrat. Décortiquons cette zone.

Distinguez la panne du proxy de la panne de l'amont

Avec un proxy, le client reçoit des erreurs de trois origines, et il faut y réagir différemment :

  • Erreurs de connexion au proxy. Impossible de se connecter au proxy, le proxy renvoie 407 (authentification requise), le proxy ferme la connexion avant l'envoi de la requête. La requête n'a certainement pas atteint le serveur. La reprise est sûre même sans clé, mais avec clé c'est toujours mieux.
  • Erreurs du proxy lors de l'appel à l'amont. Le proxy renvoie 502 Bad Gateway ou 504 Gateway Timeout. Ici l'incertitude est maximale : un 502 signifie généralement que l'amont n'a pas répondu correctement, mais a pu exécuter l'opération ; un 504 signifie que le proxy a cessé d'attendre alors que le serveur traite peut-être encore. Reprise uniquement avec clé.
  • Réponses de l'amont ayant traversé le proxy. 500, 503, 429 du serveur cible. Leur sémantique est définie par le contrat de l'API cible. Reprise avec clé selon les règles de la politique de reprise.

Un cas mérite une attention particulière : la coupure de connexion pendant la lecture de la réponse. Les en-têtes sont arrivés, le corps s'est interrompu. C'est le cas le plus perfide : vous avez peut-être vu un 201 Created, mais vous n'avez pas récupéré l'identifiant de commande dans le corps. Une reprise avec clé renverra le snapshot complet de la réponse. Sans clé, vous obtiendrez une seconde commande et vous ne connaîtrez toujours pas l'identifiant de la première.

La rotation d'IP comme événement, pas comme arrière-plan

Si votre pool de proxies mobiles fait tourner les adresses selon un planning, synchronisez l'envoi des opérations critiques avec les fenêtres de stabilité. Astuce simple : demander à l'API du service de proxy le temps restant avant la prochaine rotation et ne pas lancer la création d'une commande si le délai avant rotation est inférieur à votre timeout d'attente de réponse. Cela ne remplace pas l'idempotence, mais réduit le nombre de reprises, donc la charge sur le stockage des clés et sur l'anti-fraude du partenaire.

Si la rotation se fait à la demande, n'appelez pas un changement d'IP entre les tentatives d'une même opération sans nécessité. Certaines équipes le font « pour contourner un blocage », mais le serveur, voyant la même clé venant d'une nouvelle adresse, peut déclencher une vérification supplémentaire. La clé évitera le doublon, mais la reprise pourra ralentir.

Timeouts : deux frontières au lieu d'une

En connexion directe, on définit généralement un seul timeout pour la réponse. Via proxy, il en faut au moins deux : un timeout d'établissement de connexion au proxy (court, quelques secondes) et un timeout d'attente de réponse de l'amont (plus long, tenant compte du temps de traitement de la commande). Si on les fusionne en un seul, un timeout court se déclenchera constamment sur un traitement lent, générant des reprises inutiles, et un timeout long fera attendre un proxy inaccessible plusieurs secondes de trop.

Important : le timeout d'attente de réponse ne doit pas être inférieur au temps réel de création de la commande sur le serveur. Sinon vous couperez systématiquement la connexion au moment même du traitement, et chaque opération deviendra une paire « tentative coupée plus reprise ». La clé évitera les doublons, mais le serveur gaspillera des ressources à traiter dans le vide.

Reprise via un autre proxy

Stratégie raisonnable : la première tentative de reprise passe par le même proxy (la connexion a peut-être juste vacillé), la seconde par un autre proxy du pool (le problème vient peut-être d'un canal précis). La clé ne change pas. Le corps ne change pas. Seule la route change. Vous séparez ainsi les problèmes réseau des problèmes de la requête elle-même et vous obtenez une information de diagnostic : si ça passe immédiatement par le second proxy, le problème était le canal.

Protocole pas à pas d'une reprise sûre

  1. Lire la clé et le corps dans l'enregistrement local d'intention.
  2. Envoyer la requête via le proxy courant avec deux timeouts.
  3. En cas de succès : enregistrer le résultat, terminer.
  4. En cas de 409 du serveur : attendre le délai indiqué ou un intervalle raisonnable, réessayer avec la même clé.
  5. En cas de 422 avec un code de non-concordance d'empreinte : s'arrêter, déclencher un incident, ne pas réessayer automatiquement.
  6. En cas d'erreur de connexion au proxy : changer de proxy, réessayer immédiatement.
  7. En cas de 502, 504, coupure ou timeout : appliquer la politique de délai, réessayer avec la même clé ; à partir de la seconde reprise, via un autre proxy.
  8. Après épuisement des tentatives : laisser l'enregistrement à l'état unknown, le transmettre à la file de réconciliation (voir Méthode 4).

Le point huit est critique. L'état « je ne sais pas si la commande a été créée » est un état légitime, et il ne faut le réduire en silence ni à « créée », ni à « non créée ».

Méthode 4 : quand le serveur ne supporte pas les clés d'idempotence

Le monde idéal s'arrête dès la première API partenaire dont la documentation ignore le mot « idempotence ». Que faire si vous êtes client et que le serveur crée simplement une commande à chaque POST ? Plusieurs techniques existent, du plus simple au plus architectural.

Clé naturelle dans les champs de la requête

Beaucoup d'API, sans Idempotency-Key formelle, acceptent un champ du type external_order_id, client_reference, merchant_order_number et promettent l'unicité sur ce champ dans le périmètre du compte. C'est de l'idempotence sous un autre nom. Consultez la documentation et, surtout, vérifiez le comportement : envoyez deux requêtes avec le même identifiant externe dans un environnement de test et regardez si une erreur de doublon revient ou si une seconde entité est créée. Les promesses de la doc et le comportement réel divergent plus souvent qu'on ne le voudrait.

Lecture avant reprise

Si le serveur permet de rechercher des entités par votre identifiant externe ou par paramètres (par exemple une liste de commandes filtrée par date et montant), faites une requête de vérification avant chaque reprise : la commande avec mes marqueurs est-elle déjà apparue ? Cela ne donne pas de garantie stricte (une fenêtre peut se glisser entre la vérification et la reprise), mais réduit la probabilité de doublon d'un ordre de grandeur. Le schéma :

  1. La première tentative s'est terminée de façon indéterminée.
  2. Attendre un intervalle suffisant pour que le traitement serveur se termine.
  3. Exécuter un GET filtré par identifiant externe ou par combinaison unique de champs.
  4. Si la commande est trouvée — fixer son identifiant, la reprise est inutile.
  5. Si elle n'est pas trouvée — répéter le POST.

Pour que la recherche fonctionne, intégrez dans la commande un marqueur permettant de la retrouver : commentaire, champ personnalisé, numéro de ligne unique. Même si le serveur l'ignore comme clé, il le renverra dans la réponse, et vous pourrez faire la comparaison.

Séparer l'opération en réservation et confirmation

Certaines API supportent un modèle en deux phases : d'abord on crée un brouillon ou un hold (une opération qu'on peut répéter ou annuler sans risque), puis on confirme par l'identifiant du brouillon. La confirmation par identifiant est par nature idempotente : on ne confirme pas deux fois le même brouillon. Si un tel modèle est disponible, il est préférable à une création en une étape, même avec des clés, parce qu'il réduit la fenêtre d'incertitude de l'étape la plus risquée.

Le patron Outbox de votre côté

Même si le serveur ne garantit rien, vous pouvez garantir que de votre côté chaque opération partira avec une seule intention. L'Outbox transactionnel est une table d'opérations sortantes où l'écriture se fait dans la même transaction que la modification métier (par exemple le passage du panier au statut « en cours de commande »). Un processus émetteur séparé récupère les enregistrements de l'Outbox et exécute les requêtes via le proxy. Chaque enregistrement a un identifiant unique que vous utilisez comme clé ou comme external_id. Même si l'émetteur tombe en plein travail, l'enregistrement reste dans l'Outbox, et la reprise partira avec le même identifiant.

La réconciliation comme dernière ligne de défense

La réconciliation, ou rapprochement, est un processus régulier qui compare la liste de vos opérations avec la liste des entités côté partenaire et détecte les écarts : commandes présentes chez le partenaire mais non rattachées chez vous ; opérations au statut unknown ; doublons aux marqueurs identiques. La réconciliation n'empêche pas le doublon, mais elle le trouve en quelques minutes au lieu d'un mois plus tard dans un rapport comptable. Pour les opérations passant par des canaux instables, c'est un composant obligatoire, pas une option.

En pratique : lancer la réconciliation toutes les 10 à 15 minutes pour les opérations plus anciennes que votre timeout maximal de reprise, rattacher automatiquement les entités trouvées aux enregistrements in unknown, et transférer les doublons détectés dans une file d'annulation avec validation manuelle au-dessus d'un certain montant.

Saga et compensations

Si la commande fait partie d'une chaîne d'actions (réservation de stock, paiement, livraison), un doublon dans un maillon casse toute la chaîne. Le patron saga suppose que chaque étape a une action compensatoire : annulation de commande, remboursement, libération de réservation. La compensation doit elle aussi être idempotente, sinon vous vous battrez contre des doublons d'annulations. En concevant l'intégration, listez immédiatement les paires « action — compensation » et vérifiez que la reprise est sûre pour les deux.

Erreurs classiques : comment les équipes créent elles-mêmes les doublons

Erreur 1. La clé est générée à l'intérieur du client HTTP

La plus répandue. Un wrapper au-dessus de la bibliothèque HTTP ajoute l'en-tête Idempotency-Key avec un nouvel UUID à chaque appel. Le mécanisme de reprise à l'intérieur de la même bibliothèque relance l'envoi — et obtient une nouvelle clé. Extérieurement tout semble correct : l'en-tête est présent. En réalité, il n'y a aucune protection. Vérifiez dans les logs serveur ou proxy que la clé reste identique en cas de reprise.

Erreur 2. La clé change avec le corps lors d'une « correction » de la requête

Le client a reçu un 400 à cause d'un champ invalide, a corrigé le champ et a réessayé avec la même clé. Le serveur avec vérification d'empreinte renverra 422. Le serveur sans vérification renverra l'erreur 400 mise en cache, et le client se cognera au mur. Une requête corrigée est une nouvelle opération ; elle a besoin d'une nouvelle clé.

Erreur 3. Vérification de la clé par SELECT, puis INSERT

Déjà traité plus haut, mais répétons : entre la lecture et l'écriture, une reprise parallèle se glisse. C'est particulièrement visible avec un proxy, parce que les timeouts côté client génèrent des reprises à quelques secondes d'intervalle, tandis que le traitement de la commande prend le même temps. Seule la réservation atomique fonctionne.

Erreur 4. Idempotence par IP ou par session

Le serveur « retient » qu'une requête identique vient de partir de cette IP et rejette la reprise. Avec la rotation du proxy mobile, la reprise arrive d'une autre adresse et la protection ne se déclenche pas. L'inverse est tout aussi mauvais : des commandes légitimement différentes depuis une même adresse proxy (vous avez plusieurs clients derrière une même IP) sont rejetées comme doublons. La clé doit être explicite et transmise par le client.

Erreur 5. TTL trop court

Les clés vivent cinq minutes, « pour ne pas encombrer Redis ». La panne réseau dure vingt minutes. La file de reprises atteint l'opération au bout d'une demi-heure. La clé est oubliée, la commande est créée une seconde fois. Le TTL doit couvrir le scénario réaliste le plus long de reprise différée.

Erreur 6. Mise en cache des erreurs d'infrastructure

La première tentative a échoué avec un 500 dû à une indisponibilité temporaire de la base. Le serveur a enregistré le 500 comme résultat pour la clé. Toutes les reprises suivantes reçoivent le 500 du cache, alors que la base est remontée depuis longtemps. Le client est obligé de changer de clé, perdant le lien avec l'opération d'origine. On ne peut mettre en cache que les résultats déterministes.

Erreur 7. Réduire l'état unknown

Après épuisement des tentatives, le client marque l'opération comme failed et permet à l'utilisateur de commander à nouveau. Mais le serveur a exécuté la première opération. L'utilisateur se retrouve avec deux commandes et un double débit. L'état unknown doit exister explicitement et être résolu par réconciliation, pas par une supposition optimiste.

Erreur 8. Reprise d'opérations non idempotentes « parce que c'est plus simple »

Une couche de reprise universelle répète toutes les requêtes de la même façon, y compris les POST sans clé. Cela fonctionne jusqu'à la première tempête réseau, après laquelle apparaissent des centaines de doublons en une heure. La couche de reprise doit savoir quelles requêtes peuvent être répétées, et refuser de répéter les non idempotentes sans clé explicite.

Erreur 9. Une seule clé pour tout un lot

Le client envoie un tableau de cent commandes avec une seule clé. Le serveur en a traité soixante et est tombé. La reprise avec la même clé obtient un 409 ou un snapshot partiel. Comment savoir lesquelles des quarante restantes créer ? Pour les lots, il faut soit une clé par élément, soit une garantie serveur d'atomicité du lot complet, soit une réponse avec statut par élément. Sans cela, les lots via un canal instable sont une source de chaos.

Erreur 10. Absence de clé dans les logs

Le doublon s'est produit, et vous essayez de comprendre s'il s'agissait d'une reprise avec la même clé (bug serveur) ou de deux opérations différentes (bug client). Les logs ne contiennent pas la clé. L'enquête tourne à la divination. La clé doit figurer dans chaque ligne de log des deux côtés et dans le journal du proxy, si le service de proxy prend en charge la journalisation des en-têtes.

Outils et ressources pour la mise en œuvre

Côté client

  • Bibliothèques d'identifiants. Les générateurs d'UUIDv7 et d'ULID existent pour tous les langages principaux. Choisissez ceux qui garantissent la monotonie au sein d'une milliseconde, si les clés vont dans les index de la base serveur.
  • Clients HTTP à timeouts séparés. Vérifiez que votre client permet de définir séparément le timeout de connexion au proxy et le timeout de lecture de la réponse. La plupart des clients modernes le permettent, mais le réglage par défaut est souvent un timeout unique.
  • Files d'attente avec garantie de livraison. Pour implémenter l'Outbox, n'importe quel système de message avec accusé de traitement convient. L'important est que l'identifiant du message soit stable entre les livraisons répétées — il sera pratique comme base de clé.
  • API de gestion du proxy. Les services de proxies mobiles de qualité proposent une interface programmatique pour connaître l'état du canal, le délai avant rotation, changer d'IP à la demande. L'intégration à cette API permet de ne pas commencer d'opérations critiques avant la rotation et de changer de route consciemment entre les tentatives.

Côté serveur

  • Base relationnelle avec index uniques. La variante la plus fiable pour un stockage de clés, si les volumes le permettent. L'insertion avec gestion du conflit est atomique nativement.
  • Redis ou équivalent. Pour les systèmes à forte charge : SET avec les options NX et EX pour la réservation, une clé distincte pour le snapshot de réponse. Attention au risque de perte de données en cas de panne de nœud : configurez la persistance.
  • Middlewares d'idempotence. Pour les frameworks web populaires, il existe des couches intermédiaires prêtes à l'emploi implémentant le contrat de base : réservation, empreinte, snapshot. Vérifiez comment ils se comportent en cas de reprises concurrentes et en cas de chute entre exécution et fixation — c'est là que les bonnes implémentations se distinguent des formelles.
  • Passerelles API. Certaines passerelles savent dédupliquer sur l'en-tête en entrée. Cela soulage l'application, mais la passerelle ignore généralement le résultat métier et peut mettre en cache des erreurs d'infrastructure. À utiliser comme premier filtre, pas comme protection unique.

Tests

  • Injection de pannes réseau. Des outils proxy de test savent couper la connexion après l'envoi de la requête mais avant la réponse, retarder la réponse au-delà du timeout, renvoyer 502 et 504. Sans ces tests, vous ne verrez pas le comportement du système dans le seul scénario qui compte.
  • Tests concurrents. Envoi simultané de N requêtes avec la même clé. Résultat attendu : exactement une entité créée, N-1 réponses 409 ou snapshots. Tout autre résultat est un défaut.
  • Test de redémarrage en pleine opération. Tuer le processus après la création de la commande mais avant la fixation de la clé. Vérifier que le mécanisme de récupération des enregistrements bloqués a fonctionné.
  • Test de rotation. Première tentative via une IP, reprise via une autre. Vérifier que le serveur a renvoyé le snapshot, et non rejeté la reprise par heuristique.

Standards et documents

Le brouillon de spécification IETF sur l'en-tête Idempotency-Key est le point de départ pour formuler le contrat : il y définit le nom de l'en-tête, la sémantique des conflits et les codes de réponse recommandés. La documentation publique des grands prestataires de paiement est un bon modèle pour décrire le contrat aux intégrateurs externes : TTL, comportement en cas de non-concordance du corps, gestion des requêtes concurrentes. La section sur les méthodes idempotentes dans la spécification de sémantique HTTP explique pourquoi PUT et DELETE peuvent être répétés et POST non, et cela vaut la peine d'être relu avant de concevoir les points de terminaison.

Cas concrets et résultats

Cas 1. Un agrégateur de commandes et 47 doublons par mois

Une société d'agrégation transmettait des commandes vers le système d'un partenaire logistique via un pool de proxies mobiles avec rotation toutes les cinq minutes. Volume : environ 12 000 commandes par jour. Pas de clés d'idempotence : l'API partenaire ne les documentait pas. Les doublons étaient détectés une fois par mois par le rapprochement financier, chacun coûtant en moyenne 900 euros en annulation, remboursement et traitement manuel.

Le diagnostic sur les logs proxy a montré que 0,4 % des requêtes se terminaient par une coupure de connexion après l'envoi du corps et avant la réception de la réponse, principalement pendant les minutes de rotation. La reprise partait trois secondes plus tard, et dans 30 % des cas la première tentative était déjà exécutée à ce moment-là. Le calcul correspondait aux doublons observés.

Solution en trois étapes. Premièrement, il s'est avéré que l'API partenaire acceptait un champ external_id et rejetait les doublons sur ce champ, même si la documentation ne le mentionnait qu'en une ligne. Le champ a été rempli avec un identifiant stable issu de l'Outbox local. Deuxièmement, les fenêtres de rotation ont été synchronisées avec l'envoi : les nouvelles commandes n'étaient plus envoyées dans les 15 secondes précédant la rotation. Troisièmement, une réconciliation toutes les 10 minutes a été ajoutée. Résultat sur le trimestre : zéro doublon, nombre de reprises réduit de 70 % grâce à la synchronisation avec la rotation, temps moyen de commande allongé de 1,2 seconde à cause de l'attente des fenêtres — un prix acceptable.

Cas 2. Un service de paiement et les reprises concurrentes

Un service fintech a implémenté l'idempotence de son côté : l'en-tête était accepté, la clé enregistrée en base, et un snapshot renvoyé en cas de reprise. Les doublons apparaissaient quand même, rarement mais régulièrement : environ un pour 40 000 opérations. L'enquête a montré que la vérification de la clé se faisait par une lecture puis une écriture, et que des clients aux timeouts agressifs (deux reprises en une seconde via des proxies différents) tombaient dans la fenêtre entre les deux.

On est passé à une insertion avec index unique et on a ajouté un état in_progress avec une réponse 409 et un en-tête Retry-After d'une seconde. Une métrique de reprises concurrentes a été ajoutée. Elle a révélé un fait inattendu : 2 % de toutes les opérations reçoivent au moins un 409, ce qui signifie que les clients réessaient beaucoup plus agressivement que prévu. Le service a mis à jour sa documentation avec des recommandations de timeouts, et en deux mois la part de 409 est descendue à 0,3 %. Doublons : zéro sur six mois.

Cas 3. Une intégration marketplace et les lots

Un vendeur chargeait stocks et prix sur un marketplace par lots de 500 positions via proxy. L'idempotence du lot portait sur toute la requête. En cas de coupure, la reprise soit était rejetée (lot en cours), soit renvoyait un snapshot de résultat partiel, duquel on ne pouvait pas déduire quelles positions avaient été mises à jour. Le vendeur en concluait « rien n'a été mis à jour » et rechargeait, créant des courses entre l'ancien et le nouveau lot.

Solution : passer à des lots avec des identifiants d'opération par élément et demander un statut par élément après une fin indéterminée. La taille des lots a été réduite à 100 positions pour que le temps de traitement ne dépasse pas le timeout. Le nombre de mises à jour « bloquées » est passé de dizaines par jour à zéro, et les écarts de stocks, qui provoquaient régulièrement des annulations de commandes d'acheteurs, ont disparu.

Cas 4. Un agent automatisé et les reprises en chaîne

Tendance 2026 : de plus en plus d'intégrations sont réalisées par des agents autonomes basés sur de grands modèles de langage, qui appellent des API sur instructions. Une équipe a déployé un tel agent pour passer des achats auprès de fournisseurs. En cas de réponse indéterminée, l'agent « raisonnait » et décidait de répéter l'opération en générant une nouvelle requête. Il n'y avait pas de clés, puisque l'agent formait l'appel à chaque fois de zéro. En une semaine : 11 doublons d'achats.

Correction : on a interdit à l'agent de former directement les requêtes de création. Il crée un enregistrement d'intention dans l'Outbox via un outil interne, et l'envoi est effectué par un service déterministe avec clés et réconciliation. L'agent ne reçoit que le statut final. Les doublons ont disparu, et une traçabilité complète de qui a initié chaque achat et pourquoi est apparue en prime. Conclusion générale : les systèmes autonomes capables de reprises sont une source nouvelle et puissante de doublons, et la barrière d'idempotence est obligatoire pour eux.

FAQ : questions complexes sur l'idempotence et les reprises

Faut-il une clé d'idempotence pour PUT et DELETE, s'ils sont idempotents par spécification ?

Formellement non : une reprise de PUT avec le même corps donnera le même état. Mais il y a des nuances. Si PUT renvoie 201 à la création et 200 à la mise à jour, la reprise renverra un autre statut, et le client peut l'interpréter différemment. DELETE en reprise renverra 404 au lieu de 204, ce qui est souvent traité comme une erreur. Une clé avec snapshot de réponse rend le comportement prévisible. De plus, si PUT provoque des effets de bord (envoi de notification, écriture d'audit), ils s'exécuteront à nouveau. L'idempotence de la méthode n'égale pas l'idempotence de tous les effets de bord.

Que faire si le serveur renvoie 409 in_progress alors que la première tentative est en fait morte ?

C'est la responsabilité du serveur : il doit avoir un mécanisme de récupération des enregistrements bloqués avec un seuil de temps. Le client, lui, doit attendre un 409 non pas indéfiniment, mais un nombre limité de fois (par exemple jusqu'à deux minutes), puis passer l'opération en unknown et la transmettre à la réconciliation. Si le serveur maintient systématiquement in_progress plus longtemps que raisonnable, c'est un défaut d'implémentation à signaler au propriétaire de l'API.

Comment gérer la clé si la requête passe par plusieurs proxies en chaîne ?

Rien de spécial : la clé est transmise dans l'en-tête et traverse toute la chaîne de façon transparente. Le seul point à vérifier est qu'aucun nœud intermédiaire ne supprime les en-têtes non standard. Certaines passerelles d'entreprise filtrent les en-têtes par liste blanche. Test simple : envoyer une requête à travers toute la chaîne vers votre propre point de terminaison de débogage et vérifier que l'en-tête est bien arrivé.

Peut-on utiliser le hash du corps de la requête comme clé et ne rien stocker côté client ?

Oui, avec des réserves. Deux commandes différentes au contenu identique (même produit, même montant, même acheteur) obtiendront la même clé et la seconde sera rejetée comme reprise. Pour éviter cela, on ajoute au corps un composant unique — identifiant de panier ou numéro de séquence local. Le hash du corps devient alors une clé d'opération déterministe. Cette approche est pratique pour les clients sans stockage local fiable, mais exige une normalisation stricte du corps : un changement d'ordre des champs JSON modifiera le hash.

Combien de temps attendre avant une reprise pour que le serveur ait fini la première tentative ?

C'est une question de politique de reprise, mais du point de vue du contrat, une chose compte : si le serveur gère in_progress avec 409, il n'y a pas besoin d'attendre « au feeling » — le serveur signalera lui-même que l'opération est encore en cours. Si le serveur n'a pas cet état, l'intervalle avant reprise doit dépasser le 99e percentile du temps de traitement de l'opération côté serveur. On peut le trouver dans la documentation, dans les métriques des requêtes réussies, ou empiriquement sur un banc de test.

Faut-il rendre les opérations de lecture idempotentes ?

GET est idempotent par définition, il n'a pas besoin de clé. Mais il y a une exception : la « lecture avec effet de bord », par exemple un GET qui marque une notification comme lue ou consomme un quota. C'est une odeur architecturale ; mieux vaut transformer ces opérations en POST avec clé que d'accrocher une idempotence à un GET.

Que faire des clés lors d'une migration ou d'un changement de version d'API ?

Incluez la version du point de terminaison dans la portée de la clé côté serveur. Ainsi, une clé utilisée en v1 n'entrera pas en collision avec la même clé en v2. Pour le client, la règle est simple : une migration, ce sont de nouvelles opérations avec de nouvelles clés ; les anciennes clés ne sont pas transférées. Si une opération était en unknown au moment de la migration, résolvez-la d'abord par réconciliation, puis migrez.

Comment expliquer au métier pourquoi consacrer un sprint à l'idempotence alors que « les doublons sont rares » ?

Calculez le coût d'un doublon : annulation, remboursement, support, réputation, parfois pénalités du partenaire. Multipliez par la fréquence observée. Montrez ensuite que la fréquence croît de façon non linéaire lors des incidents réseau : un jour calme, zéro doublon ; un jour d'avarie chez l'opérateur, des centaines en une heure. L'idempotence est une assurance à prime connue et à gain inconnu mais potentiellement énorme. Elle a en plus un effet secondaire : la possibilité de réessayer agressivement sans crainte, ce qui accélère la reprise après incident.

L'idempotence augmente-t-elle la charge serveur ?

Marginalement : une écriture et une lecture supplémentaires par opération. Mais elle réduit la charge dans les scénarios de crise, parce qu'une reprise renvoie un snapshot en quelques millisecondes au lieu de retraiter toute la commande. Sous une tempête de reprises, un serveur idempotent encaisse mieux la charge qu'un serveur sans idempotence — c'est contre-intuitif, mais confirmé par la pratique.

Conclusion : un contrat plutôt qu'un espoir

Récapitulons l'essentiel. Tout réseau délivre les requêtes selon le principe « au moins une fois ». Les proxies — surtout mobiles, avec rotation et canal radio — font de la reprise non pas une rareté, mais la norme. La politique de reprise répond à la question « quand et comment réessayer ». L'idempotence répond à la question « pourquoi la reprise ne cassera rien ». Sans la seconde réponse, la première est dangereuse.

Une reprise sûre repose sur trois piliers. La clé d'opération, née avant la première tentative et vivant dans votre base, pas dans le client HTTP. Le contrat serveur avec réservation atomique, état in_progress, empreinte du corps, snapshot de réponse et TTL raisonnable. La réconciliation, dernière ligne de défense pour les opérations restées dans l'incertitude. Si le serveur ne fournit pas de contrat, l'identifiant naturel prend le rôle de clé et votre Outbox celui du stockage.

Que faire maintenant, dès aujourd'hui :

  1. Repérez dans vos intégrations toutes les opérations POST qui se répètent automatiquement. Pour chacune, répondez : y a-t-il une clé, où est-elle générée, reste-t-elle identique lors des reprises ?
  2. Lisez la documentation des API partenaires à la recherche des champs external_id et de l'en-tête Idempotency-Key. Vérifiez le comportement en environnement de test avec deux requêtes identiques.
  3. Ajoutez l'état unknown au modèle des opérations et un processus de réconciliation pour lui.
  4. Si vous possédez le serveur, passez trois tests : reprises concurrentes, chute entre exécution et fixation, reprise depuis une autre IP.
  5. Placez sur un tableau de bord le ratio reprises / opérations uniques. C'est votre indicateur de santé du canal proxy.

L'idempotence est un cas rare où la discipline d'ingénierie se convertit directement en sérénité pour le business. Un contrat conçu une fois protège pendant des années des doublons, des tempêtes de reprises et des appels nocturnes de la comptabilité. Et, honnêtement, il y a un plaisir particulier à regarder un graphique de milliers de reprises via un canal instable et à voir dans la colonne des doublons un zéro assuré.