A timeout leaves the outcome uncertain
A client sends an order and loses the connection before receiving the response. The server may already have committed the order. Sending the request again as an unrelated operation can create a duplicate. Idempotence means that repeating the same operation has the same intended effect as performing it once. It does not require every response body or status code to be identical, and it depends on a clear definition of the operation.
Identify the operation rather than just the payload
Create an operation key when the user starts the action, and reuse that key for retries. Scope it to the authenticated principal and the operation type. If the same key arrives with different order details, reject the conflict instead of silently reusing an unrelated result. Hashing the payload alone is insufficient: the user may intentionally buy the same product twice, and those two actions need different operation identities.
Make recording and effect creation atomic
If an order is stored before its deduplication record, a failure in between can leave an order that a retry cannot recognize. When possible, create the order and record its key in one database transaction, protected by an appropriate unique constraint. Concurrent duplicate requests must also compete for the same identity. An external payment system cannot usually participate in that local transaction, so coordinate its own idempotency mechanism or a recoverable state machine.
Define states, retention, and authorization
Decide what happens while an operation is still running and after it has completed. A completed request may return a stored result; an in-progress duplicate may wait or receive an explicit progress response. A key deleted after twenty-four hours cannot prevent duplicates outside that window. Match retention to the retry contract. Recheck authorization when serving a result: possession of an operation key is not permission to read another user’s transaction.
Respect the semantics behind the method name
HTTP defines the intended semantics of methods such as PUT and DELETE as idempotent, but an implementation must honor those semantics. A POST endpoint can also offer an application-level idempotency contract. Conversely, naming an endpoint PUT does not automatically deduplicate hidden billing or notification effects. Review the entire operation, including external side effects and recovery behavior, before deciding that an uncertain request can safely be retried.