Avoid duplicate business actions with idempotent requests

A user clicks submit, the screen waits, and the connection closes. The server might have completed the request. Repeating it with a new identity can create a second booking or transfer. The right question is not simply whether to retry, but how the system recognizes the same intended action.

Separate HTTP semantics from business protection

HTTP defines an idempotent method by its intended server effect: multiple identical requests have the same intended effect as one request.[2] This does not mean every response is identical or that all surrounding business activities occur exactly once. Do not apply that definition automatically to an arbitrary POST operation.

A business API can offer its own idempotency mechanism. For Stripe API v1, the documentation describes saving the initial result after execution begins and returning it for retries with the same key.[5] That is a provider-specific contract, not a universal HTTP guarantee.

Define the identity and its lifetime

Recommend one key for one intended business action. Preserve that key through connection failures and retries. Give a genuinely new action a new key. Scope the stored key to the authenticated customer and operation so unrelated tenants cannot collide.

Record a normalized request fingerprint beside the key. Reject a different payload that reuses an existing identity. Define concurrent-request behavior, retention, and the response for work still in progress. If the record expires before a delayed retry arrives, the system needs another way to detect an already completed action. Document that gap explicitly.

Ask the operations team how long delayed retries can remain possible. Use that recovery window when choosing retention, and make retries beyond the supported window a deliberate review decision.

Inspect the full execution path

A key at the API entrance does not itself coordinate a database update, an external provider, and a notification. Recommend a durable operation record and explicit recovery states. When an external outcome is uncertain, reconcile it before starting another business action.

• Choose the business action that the key identifies.
• Test simultaneous requests with the same key and conflicting payloads.
• Keep the key record and local state transition transactionally consistent where feasible.
• Define expiry, recovery, and downstream deduplication responsibilities.

Hypothetical example: an equipment reservation

Hypothetical example: an equipment rental portal creates a reservation, but the response never reaches the browser. The browser retries with the original key. The service finds the operation record and returns the existing reservation reference instead of allocating another item.

If a supplier call remains uncertain, the service reports a pending state and checks the supplier reference. It does not silently create a fresh supplier booking. This design requires storage and recovery logic. Start with the action whose duplication has the greatest operational cost, then test the failure points around every external effect.