A mobile application sends a reservation request, the server completes it, and the connection disappears before the response reaches the phone. The client cannot tell whether nothing happened or whether a booking now exists. Retrying is reasonable, but a second ordinary POST may create a second reservation. API idempotency keys give the original business attempt a stable identity so the client can repeat an uncertain request without repeating its side effect.
Consider a fictional equipment-rental service. A customer taps once to reserve a camera kit. The client creates a new key for that attempt and keeps it while retrying. If the customer later chooses a second kit, that is a new intent and needs a new key. This distinction between a retry and a new action is the foundation of the design.
Scope a key to one business attempt
Document which endpoints require a key, how long keys remain valid and which authenticated account owns them. A globally unique random value is useful, but uniqueness alone is not the complete contract. The server should bind the key to an operation and caller so a value from one workspace cannot accidentally affect another. A client should generate the key before its first request, persist it across transport retries, and discard it only when the attempt is conclusively finished or abandoned.
Do not reuse a key merely because two payloads look similar. Adding another rental unit, changing dates or intentionally placing the same order again represents new work. Treat a browser refresh, a network timeout and a mobile background-resume as retry scenarios only when they belong to the same visible user attempt.
Compare the request before replaying a result
Store a normalized fingerprint of the relevant request beside the key. When the same key arrives with a different body, route or important header, reject it instead of silently returning the earlier result. This catches a client bug that changes dates while retaining an old key. The fingerprint must be defined consistently; incidental formatting should not produce a different business meaning, while fields that change the outcome must participate.
Concurrent duplicates need an explicit state. If the first request is still processing, the second request should not begin the operation again. It can wait within a bounded policy or receive a conflict response that tells the client to retry later. The record that claims the key and the change that represents acceptance should be coordinated so two workers cannot both become the winner.
Preserve the response contract and expiry rule
A completed retry should receive the same meaningful outcome, including the created resource identifier. Decide which status and response fields are retained and what happens when a downstream action succeeds after the original connection closes. Avoid rebuilding an answer from current state if that could describe a different result. The purpose is to report the outcome of that attempt, not merely to say that something similar exists now.
Key retention has a cost, so publish an expiry rule that matches realistic retry windows and business risk. After expiry, the server can no longer promise recognition. Clients must not assume a key is permanent. Cleanup should be observable, and sensitive payloads should not be copied into the idempotency store when a fingerprint and response reference are sufficient.
Test ambiguity, concurrency and deliberate repetition
Test a lost response after the database commit, two simultaneous requests with one key, one key with two payloads, and a retry after the documented expiry. Then test two legitimate identical purchases using different keys. The first group must converge on one outcome; the last must produce two outcomes. These cases expose whether the implementation understands intent or merely compares request bodies.
The MDN Idempotency-Key reference describes the emerging header convention and the responsibilities around unique keys, fingerprints and conflicts. Your API still needs its own published policy. A reliable design makes uncertainty recoverable while keeping genuinely new customer actions possible.
For related delivery support, explore 4Minds Technology's API and backend development and custom software development. A useful implementation should leave the operating rule, evidence and ownership clear enough for the next team member to maintain. Record the final decision beside the system so future changes can be reviewed against the original purpose.



