Why does an integration contract for a 'create order' operation typically need to define an idempotency key, and what breaks in production if it doesn't?

## What idempotency means here Idempotency, in the integration sense, means that performing the same operation more than once produces the same effect as performing it exactly once. - A `GET` request is naturally idempotent — reading data repeatedly doesn't change anything. - A 'create order' `POST` is naturally not idempotent — calling it twice, by default, creates two orders. An **idempotency key** is the mechanism that makes a non-idempotent operation safe to repeat: the caller generates a unique token (commonly a UUID) once per logical business operation, attaches it to the request (often as an `Idempotency-Key` header, a convention popularized by Stripe), and resends the exact same key on every retry of that same logical operation. The server, on receiving a request, checks whether it has already processed that key: - **if not**, it processes normally and stores the key alongside the result - **if it has**, it skips reprocessing and returns the previously stored result, so the caller gets a consistent answer regardless of how many times the request was sent ## The ambiguous timeout The reason this mechanism exists is that networks fail in a specific, unavoidable way: **ambiguous timeout**. When a caller doesn't get a response before its timeout fires, there are at least three possible underlying realities: 1. the request never reached the server 2. it reached the server and failed 3. or it reached the server, succeeded, and the response was lost on the way back From the caller's side these are indistinguishable, yet the correct retry behavior differs completely: retrying is safe in the first two cases and dangerous in the third. Without an idempotency key, a caller has no way to make retrying universally safe, so teams either accept occasional duplicates, or avoid retries and accept leaving genuinely failed operations unretried — both bad trade-offs. With an idempotency key, retrying is always safe: the server-side dedup check absorbs the ambiguity. ## What it costs the server The trade-off is server-side state and a policy decision about scope and retention. The server now durably stores, per idempotency key, at least the outcome of the operation for as long as a retry might plausibly still arrive — commonly 24 hours, a window Stripe itself documents. This is genuine cost: - extra storage - an extra lookup on every write - and a design decision about key scope (unique per endpoint, per customer, or globally) and about what counts as 'the same request' — should the server also verify the retried request's body matches the original, in case a caller reuses a key for a different payload by mistake, which the contract should define behavior for (typically: reject with a conflict error rather than silently using either payload) ## Failure modes when it is left out of the contract Failure modes when this isn't in the contract are common and often expensive because they touch money or physical fulfillment. - **Duplicate charges** are the clearest example: a payment request times out client-side, the caller's retry logic fires a second identical charge request, and without an idempotency key the payment processor has no way to know these are 'the same' logical charge — the customer is billed twice, and the fix (refund, support ticket, reconciliation) is far more expensive than preventing it upfront. - **A similar failure mode shows up in message-driven systems**: a broker redelivering a message after a slow or missed acknowledgment (a normal consequence of at-least-once delivery, not a bug) causes the same 'create order' handler to run twice, producing a duplicate order row unless the handler checks for an idempotency key or an equivalent dedup key before inserting. ## A concrete worked scenario A concrete worked scenario: a mobile checkout app on a flaky connection sends `POST /orders` with `Idempotency-Key: 8f14e...`. 1. The request reaches the server, the order is created, but the response never makes it back before the app's timeout fires. 2. The app resends the identical request with the same key. 3. Without the key, the server would create a second order and — if payment capture is tied to order creation — charge the customer twice. 4. With the key, the server recognizes it's already processed, returns the original order's confirmation without creating anything new or charging anything again, and the app displays a single successful order regardless of how many times the network forced it to retry. ## What the contract should document This is why serious API contracts for any create/mutate operation that might reasonably be retried — payments being the canonical example, but also order creation, resource provisioning, or any 'do this exactly once' business action — explicitly document the idempotency key: - its required/optional status - format constraints - scope - retention window - and what error the server returns if the same key is reused with a materially different request body