Idempotency

Idempotency means "do this once, even if I ask twice." A client that times out and retries must not double-send a password reset. That is the difference between a serious transactional API and a toy.

What it does

Send Idempotency-Key as a header (authoritative) or idempotency_key in the JSON body (≤ 255 characters). The first successful accept creates the message; the key is stored with a hash of the request body. An Idempotency-Key is scoped to the application. Only POST /v1/messages honours this header. Any other endpoint ignores it.

Replay

The same key with the same body returns the original 202 — same UUID id, same status, same application_id. No extra header marks the replay (nothing like Idempotent-Replay). Both calls return the same id.

Conflict

409same key, different body

response body

{ "message": "Idempotency-Key was already used with a different request body" }

What to do: that's a bug in your retry logic — we'd rather 409 than guess which body you meant. Reuse the original key only with the original body. Do not retry a 409 with a new key for the same business event.

Retention window

Keys are honoured for 24 hours, then pruned (hourly job). After that the same string may be reused for a new message. Build the key from your domain facts — pwreset-usr_8812-20260802T1402 beats a random UUID you cannot reconstruct after a crash.