Idempotency

A network loses responses. Without care, retrying a write may launch two crawls, or generate recommendations twice, and consume your quota twice.

The principle

Send a unique Idempotency-Key header per logical operation (a UUID is enough). For 24 hours:

• the same key with the same request replays the first response, without running anything, with the Idempotent-Replayed: true header;
• the same key with another request answers 422 idempotency.key_reused;
• the same key while the first request is still running answers 409 idempotency.in_progress.

Required or accepted

Billed writes (launching a crawl, generating recommendations, tracking keywords, checking a keyword) require the key: without it, 400 idempotency.key_required. Other creations accept it. The reference says so for each operation.

curl -X POST "https://api.nessflow.com/v1/campaigns/$CAMPAIGN_ID/crawls" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Idempotency-Key: 6f1c2b0e-monday-crawl"

Replayed with the same key, the request returns the same response, and no second crawl:

curl -X POST "https://api.nessflow.com/v1/campaigns/$CAMPAIGN_ID/crawls" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Idempotency-Key: 6f1c2b0e-monday-crawl"

A 5xx response is not stored: the key stays free, and the retry really runs.