Clés d’idempotence : rendre une API sûre à relancer
Comment fonctionne une clé d’idempotence, ce que Stripe et le brouillon de l’IETF prévoient, et quoi vérifier avant de l’ajouter à votre API SaaS.
Une clé d’idempotence est un identifiant unique que le client joint à une requête pour que le serveur reconnaisse une relance et ne refasse pas l’opération. Sans elle, un délai d’attente réseau suivi d’une nouvelle tentative peut créer deux factures, deux comptes ou deux envois de courriel. Si votre API accepte des écritures et que des clients, des webhooks ou des files de messages peuvent relancer, c’est une protection simple à prévoir tôt.
Pourquoi les relances posent-elles problème?
Un client qui n’a pas reçu de réponse ne sait pas si le serveur a traité la requête. Il relance donc, et c’est normal. Le brouillon de l’IETF sur l’en-tête Idempotency-Key rappelle que, selon la RFC 9110, les méthodes OPTIONS, HEAD, GET, PUT et DELETE sont idempotentes, mais pas POST ni PATCH. Ce sont pourtant les méthodes qui créent des ressources et déclenchent des actions.
Ce brouillon propose un en-tête qui rend POST et PATCH tolérants aux pannes. En date de novembre 2026, c’est un Internet-Draft, c’est-à-dire un travail en cours et non une norme publiée. Il décrit pourtant une pratique que des API de paiement utilisent déjà.
Comment fonctionne une clé d’idempotence?
Le principe tient en quatre étapes:
- Le client génère une clé unique et l’envoie dans l’en-tête
Idempotency-Key. - Le serveur cherche la clé. Si elle est nouvelle, il exécute l’opération et conserve le résultat.
- Si la même clé revient avec la même requête, le serveur renvoie le résultat conservé sans rien refaire.
- Si la clé revient avec des paramètres différents, le serveur refuse.
- 1Requête + clé
- 2Clé connue?
- 3Sinon: exécuter, sauver
- 4Renvoyer la réponse
Si la clé est connue, le serveur saute l’exécution et renvoie le résultat sauvegardé.
Le guide de Stripe sur les requêtes idempotentes donne un exemple concret, pour son API v1 et en date de novembre 2026:
- Stripe sauvegarde le code de statut et le corps de la première requête faite avec une clé, une fois l’exécution commencée. Les relances renvoient cette réponse sauvegardée, y compris pour une erreur 500.
- Les clés font jusqu’à 255 caractères. Stripe suggère des UUID v4 ou une autre chaîne aléatoire ayant assez d’entropie, et déconseille d’y mettre des données sensibles comme un courriel.
- Les clés peuvent être supprimées après au moins 24 heures. Une clé réutilisée après sa suppression génère une nouvelle requête.
- Si les paramètres d’une relance diffèrent de ceux de l’original, il y a une erreur.
- Rien n’est sauvegardé si la validation échoue ou si la requête entre en conflit avec une autre en cours: on peut alors relancer.
Notez que ces règles sont celles de Stripe. Votre API peut choisir autrement, à condition de le documenter.
Quels codes d’erreur et quelles règles le brouillon de l’IETF propose-t-il?
Le brouillon (version 08, datée du 22 octobre 2026) formule des recommandations pour le serveur:
| Situation | Réponse proposée |
|---|---|
| Clé absente d’une opération qui l’exige | 400, avec un lien vers la documentation |
| Clé réutilisée avec un contenu différent | 422, avec un lien vers la documentation |
| Relance reçue pendant que l’original est encore en traitement | 409, avec une description du problème |
Il ajoute que la clé ne doit pas être réutilisée avec un contenu différent, qu’un UUID ou un identifiant aléatoire similaire est recommandé, et que si les clés expirent, la politique d’expiration devrait être publiée dans la documentation.
- ClientGénère la clé, la réutilise à chaque relance
- APILit l’en-tête, compare le contenu
- Base de donnéesContrainte d’unicité sur la clé
Une façon de répartir les rôles, pas une architecture imposée.
Que faut-il décider avant de l’ajouter à votre API?
Voici les décisions qui comptent. Ce sont des points à trancher, pas des règles absolues:
- Quelles routes? Commencez par celles dont un doublon coûte cher: paiements, création de comptes, envois, appels à des services tiers.
- Qui est propriétaire de la clé? Limitez la portée de la clé à un client ou à un locataire. Une clé choisie par un client ne doit pas pouvoir lire la réponse d’un autre.
- Que stocker? Une empreinte de la requête, le statut et la réponse. Prévoyez la taille et la durée de conservation, et évitez d’y mettre des renseignements personnels, comme Stripe le déconseille pour les clés.
- Quelle durée? Choisissez une durée de conservation plus longue que la fenêtre de relance de vos clients et de vos files. Stripe peut supprimer les clés après au moins 24 heures pour sa v1; la vôtre dépend de vos intégrations.
- Que faire d’une requête en cours? Renvoyer une erreur de conflit est simple. Attendre le résultat est plus confortable pour le client, mais plus complexe.
- Les erreurs aussi? Stripe v1 renvoie même les erreurs 500 sauvegardées. Décidez si une erreur transitoire doit pouvoir être relancée avec la même clé.
Comment l’essayer en toute sécurité cette semaine?
- Choisissez une seule route d’écriture à risque et acceptez l’en-tête de façon facultative.
- Ajoutez une table de clés avec une contrainte d’unicité sur (locataire, clé), pour que deux requêtes simultanées ne passent pas toutes les deux.
- Enregistrez la clé et l’empreinte avant l’opération, puis le résultat après. Les deux écritures doivent rester cohérentes avec l’effet réel, sinon une panne au milieu laisse un état ambigu.
- Écrivez les tests: même clé et même contenu, même clé et contenu différent, deux requêtes simultanées, clé expirée.
- Documentez la durée de conservation, les codes d’erreur et le format de clé recommandé.
- Surveillez le taux de relances reconnues: c’est la preuve que le mécanisme sert.
Que vérifierions-nous en premier?
Nous commencerions par chercher les endroits où un doublon coûte vraiment de l’argent ou de la confiance: les webhooks reçus, les tâches de file rejouées et les clients mobiles sur réseau instable. Ensuite, nous regarderions si l’effet de bord (le paiement, le courriel) est lui-même protégé, car une clé dans votre API ne protège pas un appel sortant sans clé vers un autre service.
Si vous voulez un regard senior sur la conception de votre API, notre page services décrit notre façon de travailler.
Cet article est de l’information générale, non un avis juridique ni de sécurité. Le brouillon de l’IETF peut changer; vérifiez les documents à jour avant de vous y fier.