Clés d’idempotence et l’art des relances sûres

Dans toute intégration distribuée, une requête qui dépasse son délai n’a pas forcément échoué : elle peut avoir réussi pendant que la réponse se perdait. Relancer naïvement transforme un hoquet passager en enregistrement dupliqué. L’idempotence est la discipline qui rend les relances sûres, et VIN Doc vous en donne les outils pour le faire proprement. Réussissez cela une fois et toute une classe d’incidents nocturnes cesse simplement de se produire.

Ce que signifie vraiment l’idempotence

Une opération idempotente peut être appliquée plusieurs fois avec le même effet qu’une seule application. Pour VIN Doc, cela signifie attacher une clé d’idempotence aux opérations d’écriture pour qu’une requête répétée renvoie le résultat d’origine au lieu d’en créer un nouveau.

POST /v1/jobs
Idempotency-Key: 9b1c-job-import-2026-06-15
{ "vins": [ ... ] }

• Générez une clé par opération logique, pas par tentative
• Réutilisez la même clé sur les relances de cette opération
• Les clés sont propres à votre compte : les collisions sont à vous d’éviter

La clé représente l’intention, pas le transport. Si vous générez une clé neuve à chaque relance, vous n’avez l’idempotence que de nom, car chaque tentative ressemble à une toute nouvelle opération pour la plateforme.

Là où les relances dérapent

L’échec classique est de relancer sur un dépassement de délai sans clé. Le premier appel a abouti, le second crée un doublon, et votre réconciliation est désormais faussée. Le second échec classique est de relancer sur un 4xx qui ne réussira jamais : un VIN malformé ne s’améliore pas en demandant deux fois, il brûle juste des requêtes et retarde la vraie correction.

Une politique de relance solide

Relancez sur les erreurs de connexion, les dépassements de délai, les 429 et les 5xx. Ne relancez pas sur un 4xx autre que 429. Utilisez un backoff exponentiel avec gigue pour qu’une flotte de clients ne se synchronise pas en troupeau bruyant. Plafonnez le nombre de tentatives et exposez un échec clair plutôt que de relancer indéfiniment.

delay = min(base * 2 ** attempt, max_delay)
sleep(delay + random_jitter())

• Ne relancez que sur les classes d’erreur transitoires
• Temporisez de façon exponentielle et ajoutez de la gigue
• Abandonnez après un nombre borné de tentatives

Rendre vos handlers idempotents aussi de votre côté

L’idempotence n’est pas qu’une affaire sortante. La même discipline de clé s’applique à la façon dont vous traitez les livraisons de webhooks et les résultats de jobs : dédupliquez sur l’identifiant d’événement ou de job pour que retraiter la même charge utile ne change rien qu’elle a déjà appliqué. Un producteur idempotent et un consommateur idempotent ensemble rendent tout le pipeline sûr à relancer en tout point.

Choisir des clés que vous pouvez régénérer

En pratique, le plus dur de l’idempotence est de décider ce que doit être la clé. Une valeur aléatoire ne marche que si vous la persistez avant la requête et pouvez la récupérer après un crash ; sinon un redémarrage perd la clé et votre tentative suivante semble toute neuve. Un meilleur motif est une clé déterministe dérivée de l’opération elle-même : la liste d’entrée, plus une date, plus un objectif, hachés en quelque chose de stable. Ainsi, même un processus qui redémarre en plein vol reconstruit la même clé à partir des mêmes entrées et la plateforme reconnaît la relance. Les clés qui survivent à un crash sont celles qui vous protègent vraiment, car le moment où vous avez le plus besoin d’idempotence est précisément celui où quelque chose a mal tourné de votre côté.

Vérifier par la réconciliation

Les clés d’idempotence vous protègent sur l’instant ; la réconciliation le prouve après coup. Comparez périodiquement ce que vous avez envoyé à ce que l’API a enregistré. Un rapport de réconciliation propre est la seule preuve réelle que votre logique de relance est correcte sous charge, et c’est une assurance bon marché contre un doublon qui fausse discrètement un rapport en aval.

L’intégrer dès le départ

Ajouter l’idempotence après un incident de données dupliquées est pénible ; la concevoir dès la première intégration est presque gratuit. Les SDK officiels gèrent les clés et les relances avec gigue pour vous, adopter des réglages sûrs par défaut est donc souvent une simple activation. Vous pouvez tout répéter contre la sandbox, où l’essai gratuit dure deux jours pour 3,99 € puis 49,99 €/mois, se renouvelant automatiquement et annulable à tout moment, avant qu’une seule vraie relance ne se déclenche en production.