What is an idempotency key in APIs?

An idempotency key is a unique value generated by the client and sent with a state-changing request (commonly in the Idempotency-Key header) so the server can recognize a retry of the same operation and return the original outcome rather than performing it again. When the server implements the key under a documented contract, this can prevent duplicate effects when a client retries a POST or PATCH. Sending a header alone does not add server-side deduplication or change the HTTP method’s formal safety semantics MDN Idempotency-Key header Stripe idempotent requests.

How idempotency keys work

Typical flow:

• Client generates a unique key (often a UUID) and includes it in Idempotency-Key for a request that may be retried.
• Server checks if that key has been seen. If not, it processes the request and stores the outcome associated with the key. If seen again with the same request, it returns the stored outcome instead of repeating the operation MDN Idempotency-Key header.

Providers refine this pattern. For example, Stripe stores the status code and body of the first request for API v1 and returns the saved response on retries (including errors). They recommend V4 UUIDs, avoid sensitive data, and note keys may be pruned after at least 24 hours in v1 Stripe idempotent requests.

Servers often implement an idempotency fingerprint by hashing relevant request parts (method, path, body) to ensure a reused key with different input is rejected. MDN documents recommended error semantics: 400 when a required key is missing, 409 if a request with the same key is still processing, and 422 if the same key is used with a different payload MDN Idempotency-Key header.

When to use an idempotency key

Use keys with operations that are not idempotent by default and may be retried: POST and many PATCH requests. GET, HEAD, PUT, and DELETE are defined as idempotent by HTTP semantics, so clients can already retry them safely from a protocol perspective, even though responses may differ between attempts MDN idempotent glossary. If your provider supports it, adding Idempotency-Key to state-changing operations protects against duplicates during network issues and timeouts What is an API timeout? Yandex Cloud idempotency.

Implementing idempotency keys: client and server steps

Client steps

• Generate a high-entropy unique key per logical operation (for example, a V4 UUID) and persist it until you receive a final outcome.
• Send the key in the Idempotency-Key header on the initial request and all retries.
• Do not include sensitive data in keys. Stripe suggests random strings/UUIDs and documents size limits, with retries returning the saved response in v1 Stripe idempotent requests.

POST /api/orders HTTP/1.1
Host: example.test
Content-Type: application/json
Idempotency-Key: 6b2f7f2a-2a3e-4d0a-a2f8-3e5b2d5c8f11

{"items":[{"sku":"BK-123","qty":1}]}

Server behavior

• On first-seen key: mark it as processing, run the operation, then store the final status and body as the canonical result for that key. Return it to the client.
• On duplicate with same fingerprint: return the stored result without re-running business logic.
• Error semantics to document: 400 when a required key is missing, 409 while the first request with that key is still running, and 422 if the key is reused with a different payload MDN Idempotency-Key header. See HTTP 409 Conflict for handling guidance.
• Expiry/TTL: document how long keys are retained so clients can plan retry windows. Stripe notes pruning after at least 24 hours for API v1 as an example policy Stripe idempotent requests.

Testing and edge cases

• Timeout then retry: simulate a client timeout and confirm the retry with the same key returns the original outcome and does not duplicate work What is an API timeout?.
• Concurrent duplicates: fire two identical POSTs in parallel with the same key. One should process; the other should receive a stored response or a temporary 409 if the first is still processing MDN Idempotency-Key header.
• Mismatched reuse: resend the same key with different parameters; the server should reject it (for example, 422) per documented behavior MDN Idempotency-Key header.
• Remember: idempotency concerns server effect, not identical responses. Status codes and bodies may differ between repeats, and that is still idempotent if the server state is unchanged beyond the first application MDN idempotent glossary.

Short FAQ