Idempotence

Rejouer une requête sans jamais créer de doublon, grâce à l’en-tête Idempotency-Key.

Sur Internet, une requête peut échouer après avoir réussi : votre serveur ne reçoit jamais la réponse, et réessaie. Sans protection, vous créeriez deux produits, deux codes promo ou deux liens de paiement.

L’en-tête Idempotency-Key règle ce problème : vous donnez à l’opération un identifiant unique, et Pulse-Sell garantit qu’elle n’est exécutée qu’une seule fois, quel que soit le nombre d’envois.

curl -X POST https://api.pulse-sell.com/v1/discounts \
  -H "Authorization: Bearer $PULSESELL_API_KEY" \
  -H "Idempotency-Key: promo-rentree-2026-v1" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Rentrée", "code": "RENTREE20", "type": "percentage", "value": 20 }'

Règles

• S’applique à toutes les requêtes POST.
• La clé fait de 8 à 128 caractères parmi lettres, chiffres, _, -, : et .. Un UUID convient très bien.
• Elle est conservée 24 heures par clé d’API.
• Rejouer la même requête avec la même Idempotency-Key renvoie la même réponse, avec l’en-tête Idempotent-Replayed: true, sans rien refaire.
• Seules les réponses de succès (2xx) sont mémorisées : si la première tentative échoue, vous pouvez réessayer avec la même clé.

Cas particuliers

Situation	Réponse
Même clé, même requête, déjà terminée	La réponse d’origine, avec Idempotent-Replayed: true.
Même clé, contenu différent	422 idempotency_key_reuse : une clé ne peut servir qu’à une seule requête.
Même clé, première requête encore en cours	409 idempotency_in_progress avec Retry-After: 1. Réessayez dans une seconde.

Deux requêtes simultanées avec la même clé ne s’exécutent jamais toutes les deux.

Comment choisir la clé

Une action métier

Dérivez la clé de l’action : order-4521-checkout. Si votre système réessaie pour la même commande, la clé est identique, et le doublon est impossible.

Un identifiant aléatoire

Générez un UUID avant le premier envoi, stockez-le avec la tâche, et réutilisez-le à chaque nouvelle tentative. Ne générez pas une nouvelle clé à chaque essai : ce serait inutile.

Les requêtes GET, PATCH et DELETE n’ont pas besoin de clé : les lire ou les répéter ne crée rien de nouveau.