# L’idempotence

Rejouer une demande sans encaisser deux fois.
Le réseau ment : une demande peut aboutir sans que sa réponse revienne. Posez un en-tête `Idempotency-Key` sur vos `POST` — rejouée, la même clé rend la première réponse au lieu d’encaisser deux fois, avec l’en-tête `Idempotent-Replayed: true`.

**Il devient obligatoire quand l’appel touche un téléphone** : lancer une demande ([POST /v1/payments/{id}/attempts](https://docs.payiz.app/api/paiements/lancer)), ou créer un paiement avec `payer`. Sans lui, l’appel répond `idempotency_key_required` : un rejeu sans clé ferait sonner le téléphone deux fois.

```bash
curl https://api.payiz.app/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: cmd-42" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10000, "currency": "XOF" }'
```

- Une clé se garde 24 h ; passé ce délai, elle redevient libre.
- La même clé avec un autre corps répond **409** : donnez-en une nouvelle.
- Une demande refusée avant d’avoir rien écrit ne retient pas sa clé : corrigez et rejouez la même.
- **Le point de non-retour** : une fois le geste écrit, la clé lui appartient. Une panne ensuite ne rend jamais une erreur 5xx : vous recevez l’objet tel qu’il est, et un rejeu vous rend le même — la demande n’est jamais relancée.

Une clé par geste métier, pas par tentative : la référence de la commande fait une bonne clé, un identifiant tiré au hasard à chaque essai n’en fait aucune.