Conventions

Idempotency

Networks fail at the worst moment: after the server acted, before you heard back. An Idempotency-Key makes a POST safe to retry — the second attempt returns the first result instead of creating a duplicate.

Header: Idempotency-Key
Methods: POST
Kept for: 24 hours

How it works

Send a unique Idempotency-Key header — any string up to 255 characters; a UUID is ideal — with a POST. Nextora stores the response for 24 hours:

You send	Within 24 hours you get
The same key and the same body	The original response again, status included, with `Idempotent-Replayed: true`. Nothing runs twice.
The same key with a different body	`409 idempotency_key_reused`. Nothing runs.
The same key while the first request is still running	`409 idempotency_key_reused` with `details.reason: "in_progress"`. Retry shortly.
The same key for a request whose response holds a secret (creating a webhook, rotating its secret)	`409 idempotency_key_reused` with `details.reason: "not_replayable"` and `details.resource_id`: secrets are never stored, so read the resource instead of replaying.
A new key	A new request.

Sending a key

Create a lead, safely

curl -X POST https://acme.nextora.co/api/v1/leads \
  -H "Authorization: Bearer $NEXTORA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9b8c7d6e-5f4a-4b3c-8d2e-1f0a9b8c7d6e" \
  -d '{
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "source": "website"
  }'

Response201 Created

{
  "data": {
    "id": "a7c9e1b3-5f2d-4a6c-8e9b-2d4f6a8c0e13",
    "name": "Grace Whitfield",
    "email": "[email protected]",
    "phone": null,
    "company_name": null,
    "status": "new",
    "source": "website",
    "score": 0,
    "owner_id": "0c4f8e2a-7b3d-4a1f-9e6c-5d2b8a1f3e47",
    "custom_fields": {},
    "created_at": "2026-10-10T07:58:31Z",
    "updated_at": "2026-10-10T07:58:31Z"
  }
}

Retried with the same key and body, the request answers the same 201 and the same lead, marked as a replay:

Replay headers

HTTP/1.1 201 Created
Content-Type: application/json
Idempotent-Replayed: true
X-Request-Id: 5f0c2e7a-9b4d-4a1c-8e3f-6d2b9a7c1e05

Choosing keys

Make one key per operation, not per attempt: generate it when you decide to create the record, store it with your job, and reuse it for every retry of that job.
Derive keys from your own IDs when you have them — order-1042-lead — so a duplicate message from your queue is caught too.
Never reuse a key for a different request: you get 409 idempotency_key_reused, by design.