Idempotency#

Network failures, timeouts, and retries are unavoidable. The Evolu Integrators API uses an idempotency key so a retried request never creates a duplicate entry.

The Idempotency-Key header#

Every POST /v1/entries request must include an Idempotency-Key header.

Omitting it returns 422 Unprocessable Content.

How it works#

The key identifies a single entry within your campaign and livemode — its scope is (campaign, livemode, Idempotency-Key). On submission:

• First time seen — the entry is created and processed normally.
• Seen again — the API skips creation and returns the original entry's entry_id and current status, with a message noting the replay.

Either way the response is 202 Accepted, so a retry is always safe.

Test and live are independent#

The key is scoped per livemode, so the same Idempotency-Key used with a test-mode key (evolu_test_*) and a live-mode key (evolu_live_*) refers to two independent entries — they never collide. Deduplication happens within a mode: a retry with a test key matches the earlier test entry, and a retry with a live key matches the earlier live entry. This lets you rehearse an integration in test mode and reuse the very same keys in production without a single test submission shadowing a real one.

{  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "status": "PENDING",  "message": "Entry accepted for processing."}

{  "entry_id": "01905a3b-7c8d-7f00-a1b2-c3d4e5f6a7b8",  "status": "APPROVED",  "message": "Entry already exists for this idempotency key."}

Best practices#

• Generate one key per logical entry. Reuse the same key when retrying that entry; use a new key for a genuinely new entry.
• Persist the key alongside the entry in your system before sending the request, so a crash-and-retry reuses it.
• UUIDs are ideal — they are unique without coordination.