Idempotence

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.

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 :

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.