Idempotency

Send an Idempotency-Key on a write and a retry cannot create a second one.

Updated 16 Sep 20261 min read

A network can fail after we have acted and before you have heard about it. Send an Idempotency-Key header with a write and a retry returns the original response instead of doing the work twice.

curl https://api.mockflow.com/v1/boards \
  -X POST \
  -H "Authorization: Bearer $MOCKFLOW_API_KEY" \
  -H "Idempotency-Key: 8f14e45f-ea0a-4b2d-9c1e-5f0a2b7c1d33" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Q4 Launch Planning" }'

The rules

One key per logical request

Generate a UUID when you build the request, not when you retry it. A key reused for different work defeats the point.

Replays are exact

A repeat within 24 hours returns the first response, status and body, with Idempotency-Replayed: true on it. Nothing is created twice.

A different body is a conflict

The same key with a body that does not match the first is answered 409 conflict, rather than quietly returning someone else's result.

After 24 hours the key is forgotten

A retry that late is a new request. This is why the window is long enough to cover a retry queue and short enough to bound the store.

Only a POST reads the header. GET, PATCH, PUT and DELETE are already safe to repeat, so a key on them is ignored.

Was this page helpful?