IdempotencyKey - Nova

Send an Idempotency-Key header on a POST, PUT, PATCH or DELETE request to make it safe to retry. The first request runs and its response is stored; a retry with the same key gets that stored response back without the operation running again. The header is ignored on reads.

curl -X POST https://api.nova.net/v1/distributions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 6c3e1f7a-2b9d-4f0e-8a51-0d7c4b2e9f13" \
  -H "Content-Type: application/json" \
  -d @distribution.json

Use a new random value, such as a UUID, for each distinct operation, and reuse it only when retrying that operation.

Retries

What happened to the first request	What a retry with the same key gets
Finished with a `2xx` or `4xx` (other than `408` and `429`)	The stored response, replayed
Still running	`409` with code `conflict`. Wait briefly and retry
Failed with a `5xx`, `408` or `429`	Nothing stored; the request runs again
Sent a different request with this key	`422` with code `idempotency_mismatch`

A request counts as different when its method, path, organization or body differ from the first request with that key. A 401, an X-Organization-Id error or a body that isn’t valid JSON is rejected before the key is read, so it is never stored.

Scope and retention

Keys are scoped to your integration, so they never collide with another integration’s keys. Keys are kept for 24 hours and deleted within the following hour. Until a key is deleted, reusing it still replays the stored response, or returns 422 if the request differs.

Last modified on October 27, 2026