Une API de paiement idempotente, c'est une API qui, à clé d'idempotence égale, renvoie le même résultat quel que soit le nombre de fois où la requête est rejouée. En production, les retries ne sont pas optionnels — c'est le comportement par défaut de tout client correctement implémenté.
Le mécanisme est simple en principe : chaque écriture est indexée par un jeton d'idempotence, le grand livre enregistre la première écriture réussie sous cette clé, et les requêtes suivantes avec la même clé court-circuitent vers le résultat en cache. La discipline se joue dans les bords.
Trois règles se sont avérées porteuses. Primo : la clé doit couvrir l'intention entière de l'appel — pas seulement le montant, mais l'ensemble de la machine à états. Deuxio : le cache doit persister assez longtemps pour couvrir des fenêtres de retry réalistes, soit des jours, pas des secondes. Tertio : la réconciliation est une préoccupation de premier plan, pas un script mensuel.
Quand ces trois règles sont en place, on arrête de voir les retries comme un problème et on commence à les voir comme une garantie — le système est convergent, et un retry n'est qu'un no-op.