Reliability Required

Accept idempotency keys on POST

Let clients send an Idempotency-Key header on POST and PATCH, and return the first result for a repeated key instead of acting twice.

By Erik Bergstedt, Agent Wranglers. Updated 20 October 2026.

How to do it

Store each key with a hash of the request body and the response, for at least 24 hours. A repeat with the same body gets the stored response. A repeat with a different body gets 422, and a repeat while the first is still running gets 409. The header comes from an IETF draft, so name the draft and your expiry in the docs.

Example

POST /payments HTTP/1.1
Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324
Content-Type: application/json

{"orderId":"ord_8f2k","amount":12950,"currency":"SEK"}

How to check

Send the same POST with the same key twice. One order exists, and both answers are identical.

For agents: if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/reliability/idempotency-keys.