L’idempotence API consiste à obtenir le même résultat métier quand une même demande est rejouée. Dans les flux critiques, ce principe protège le chiffre d’affaires, la finance et le support.
Sans idempotence, un timeout peut créer deux commandes, deux paiements, deux factures ou deux écritures comptables. Le client voit un incident, l’équipe voit une dette de run.
Une intégration API sérieuse rend les retries sûrs dès le départ.
Le sujet devient prioritaire dès qu’un flux passe par webhooks, files d’attente, retries automatiques ou imports périodiques. Plus il existe de chemins pour rejouer une action, plus la clé d’idempotence doit être pensée comme une règle métier.
La règle de base
Si une action peut être rejouée automatiquement, elle doit être idempotente. Sinon, chaque retry devient une prise de risque métier.
Comprendre le coût du doublon
Un doublon ne se limite pas à une ligne en trop. Il peut déclencher une préparation logistique, une demande de remboursement, une relance comptable ou une incohérence CRM.
Le coût réel se mesure en temps support, confiance client et corrections manuelles.
Choisir une clé d’idempotence
La clé doit identifier l’intention métier, pas seulement la requête technique. Elle peut combiner source, événement, identifiant externe, type d’action et version.
Une clé trop large bloque de vrais traitements. Une clé trop fine laisse passer les doublons.
Cette clé doit rester stable malgré les retries.
Protéger les commandes
Pour une commande, l’idempotence doit distinguer création, mise à jour, annulation et changement de statut. Chaque intention doit avoir son propre cadre.
Le système doit reconnaître qu’une commande déjà créée ne doit pas être recréée, mais peut recevoir un statut plus récent.
Protéger les paiements
Les paiements exigent une prudence maximale. Un retry ne doit jamais capturer deux fois une même intention de paiement ou créer deux remboursements.
Il faut conserver le lien entre transaction externe, commande interne et décision financière.
La clé d’idempotence doit survivre aux reprises support et aux webhooks tardifs. Sinon, l’équipe peut corriger un incident client tout en créant un second écart côté PSP, facture ou comptabilité.
Protéger les factures
Les factures et avoirs doivent être dédupliqués selon les règles comptables. Un simple identifiant technique ne suffit pas toujours.
L’idempotence doit respecter la source de vérité et produire une trace exploitable par la finance.
Une facture déjà émise ne se traite pas comme une commande encore modifiable. Le flux doit distinguer création, annulation, avoir et correction administrative pour éviter des écritures incohérentes.
Gérer webhooks et retries
Les webhooks peuvent être livrés plusieurs fois, parfois dans un ordre inattendu. Les retries côté client peuvent aussi rejouer une demande après timeout.
L’API doit accepter ces répétitions sans créer de nouvel effet métier non voulu.
Stocker les décisions
Il faut stocker la clé, la requête utile, la décision prise, le résultat et l’état du traitement. Ce journal permet de répondre au même retry avec le même résultat.
La trace doit être assez claire pour expliquer l’incident à un support ou à une équipe finance.
Traiter la concurrence
Deux traitements peuvent arriver au même moment. L’idempotence doit donc s’appuyer sur des contraintes atomiques, pas seulement sur un test applicatif fragile.
La base de données, la file ou le verrou doivent empêcher la double décision.
Auditer et rejouer
Le run doit permettre de retrouver une clé, comprendre la décision et rejouer un flux sans effet secondaire.
La reprise doit afficher clairement si la demande a créé l’objet, réutilisé une décision existante, ignoré un doublon ou rejeté une intention incompatible.
- Définir les intentions métier.
- Choisir des clés stables.
- Tracer les réponses.
- Bloquer les doubles écritures.
- Tester les retries et timeouts.
Conclusion : rendre le retry sûr
L’idempotence transforme un retry dangereux en mécanisme fiable. Elle protège commandes, paiements, factures et équipes opérationnelles.
Pour compléter le sujet côté architecture événementielle, lisez webhooks vs polling.
