> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pulse-sell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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.

> [!TIP]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.