Designing idempotent operations and safe retries

Goal

A client whose request ends in a timeout should be able to retry it safely: no duplicate order, no duplicate payment, no duplicate item.

Prerequisites

RFC 9110 calls a method idempotent if the intended effect on the server of multiple identical requests is the same as the effect of a single request. PUT, DELETE and the safe methods (GET, HEAD, OPTIONS, TRACE) are idempotent; POST is not. The same RFC states that a client should not automatically retry a request with a non-idempotent method unless it knows that the request semantics are actually idempotent. For POST, the IETF draft "The Idempotency-Key HTTP Header Field" (HTTPAPI working group; version 07 of October 2025, expired as of September 2026 and not published as an RFC) describes the header used by Stripe and other providers. You need a store for a small record per key, and clients that generate a unique key for each logical operation.

Steps

1. Choose methods according to RFC 9110: use PUT to modify a resource at a known address and DELETE to remove it; both may be retried without additional mechanisms.
2. For POST requests that create resources, accept an Idempotency-Key header. The draft recommends a UUID or a similarly random identifier; Stripe suggests V4 UUIDs, allows up to 255 characters and advises against using sensitive data as keys.
3. When a key first arrives, store it together with a fingerprint of the request (a hash over path and body), the account, and the result (status, response body). Do this in the same transaction as the operation itself or under a lock on the key, so that two concurrent retries cannot both go through.
4. If the key arrives again with the same fingerprint, return the stored response unchanged. If the same key arrives with a different body, respond with 422, as the draft specifies; if the original request is still being processed, respond with 409.
5. Delete keys after a documented retention period. Stripe describes removal after at least 24 hours and treats a key reused after that as a new request.
6. Document the key format, retention period and conflict behavior in the API documentation, so that clients and agents can rely on them instead of guessing.

Expected result

A client that retries with the same key after a timeout gets exactly one created resource and the same response both times.

Limits and test basis

Idempotency covers the state of your own server, not side effects in external systems (for example an email sent twice by a downstream service). Keys must be scoped per account, otherwise clients collide. The draft is not an RFC and is currently expired; statements about the header and status codes follow the draft and the cited Stripe documentation, and no measurement is claimed.