# Idempotence

> Réessayer une écriture sans jamais la faire deux fois, grâce à l’en-tête Idempotency-Key.

Un réseau perd des réponses. Sans précaution, réessayer une écriture peut lancer deux crawls, ou générer deux fois des recommandations, et consommer deux fois votre quota.

## Le principe

Envoyez un en-tête `Idempotency-Key` unique par opération logique (un UUID suffit). Pendant 24 heures :

- la même clé avec la même requête rejoue la **première réponse**, sans rien exécuter, avec l’en-tête `Idempotent-Replayed: true` ;
- la même clé avec une **autre** requête répond `422 idempotency.key_reused` ;
- la même clé pendant que la première requête tourne encore répond `409 idempotency.in_progress`.

## Exigée ou acceptée

Les écritures **facturées** (lancer un crawl, générer des recommandations, suivre des mots-clés, vérifier un mot-clé) **exigent** la clé : sans elle, `400 idempotency.key_required`. Les autres créations l’acceptent. La référence l’indique pour chaque opération.

```bash expect=202
curl -X POST "https://api.nessflow.com/v1/campaigns/$CAMPAIGN_ID/crawls" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Idempotency-Key: 6f1c2b0e-crawl-du-lundi"
```

Rejouée avec la même clé, la requête rend la même réponse, et aucun second crawl :

```bash expect=202
curl -X POST "https://api.nessflow.com/v1/campaigns/$CAMPAIGN_ID/crawls" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Idempotency-Key: 6f1c2b0e-crawl-du-lundi"
```

Une réponse `5xx` n’est pas mémorisée : la clé reste libre, et la relance s’exécute vraiment.