Vérifier le format d'une clé d'idempotence

Elle vérifie que la clé n'est pas vide, qu'elle est assez longue pour être unique en pratique, qu'elle reste sous une longueur maximale raisonnable et que chaque caractère est sûr dans une URL, afin que la clé traverse en-têtes, journaux et chaînes de requête sans surprise d'encodage. Vous envoyez une chaîne et recevez un indicateur valid clair, la longueur mesurée et une liste de problèmes concrets lorsque quelque chose ne va pas.

Pourquoi les clés d'idempotence ont besoin d'une vérification de format

Les clés d'idempotence existent pour qu'une requête renvoyée — un paiement soumis deux fois, une commande créée après un délai d'attente — ne soit traitée qu'une seule fois. Mais la sécurité qu'elles promettent dépend du bon format de la clé elle-même. Une clé trop courte entre en collision avec celle d'un autre client et déduplique silencieusement deux opérations différentes en une seule. Une clé contenant des caractères hors de l'alphabet sûr pour URL est déformée quelque part entre votre client, un proxy, la chaîne de journaux et le serveur, si bien que la nouvelle tentative arrive avec une chaîne différente de l'originale et est facturée deux fois. Une clé vide est rejetée d'emblée par la plupart des API, souvent avec une erreur générique qui prend un après-midi à diagnostiquer. Faire passer la clé par cette vérification de format de clé d'idempotence à la périphérie de votre système détecte les trois modes d'échec au moment du développement, dans une suite de tests ou dans une validation préalable au sein de votre propre service, plutôt que dans un rapport de rapprochement des semaines plus tard.

Ce qui est validé exactement

La vérification applique les règles de format que les prestataires de paiement et les middlewares de déduplication documentent le plus souvent. D'abord, la clé doit être une chaîne non vide ; une clé vide est une erreur, pas un avertissement, car aucun serveur ne l'acceptera. Ensuite, la longueur : par défaut, la clé doit compter au moins 16 caractères, le seuil en dessous duquel l'unicité cesse d'être plausible, et au plus 255 caractères, le plafond que la plupart des stockages acceptent — ces deux bornes sont configurables à chaque appel. Enfin, l'alphabet : chaque caractère doit appartenir à l'ensemble non réservé de la RFC 3986 — lettres, chiffres, tiret, point, tiret bas et tilde. Ces caractères traversent les en-têtes HTTP, les segments d'URL et les transporteurs de journaux sans encodage, ce qui est exactement le parcours des clés d'idempotence. Quand un caractère échoue, la réponse énumère chaque caractère fautif distinct pour que vous voyiez si quelqu'un a inséré une espace, une barre oblique ou un emoji, et le tableau issues nomme le problème de façon lisible par une machine : too_short, too_long ou unsafe_characters.

Où la vérification s'intègre dans votre stack

La plupart des équipes l'intègrent à deux endroits. Le premier est le client qui génère les clés : juste après avoir construit une clé à partir d'un UUID, d'un horodatage et d'un identifiant utilisateur, validez-la une fois et consignez un avertissement si elle échoue, afin qu'un bogue du générateur apparaisse en préproduction plutôt qu'en production. Le second est le test de contrat : envoyez un lot de clés issues de chaque intégration que vous maintenez à l'endpoint en CI, de sorte qu'une mise à jour de bibliothèque modifiant le comportement d'encodage fasse échouer le build. L'endpoint est déterministe et sans état — rien n'est stocké, aucune liste de clés déjà vues n'est consultée et la même entrée produit toujours la même sortie —, ce qui signifie qu'on peut l'appeler sans risque avec de vraies clés et qu'il est assez bon marché, à $0.002 par requête, pour s'exécuter à chaque déploiement. La même validation s'exécute aussi gratuitement dans votre navigateur sur cette page, si bien qu'un développeur peut coller une clé suspecte pendant un incident et obtenir la même réponse que celle de l'API.