Idempotency

In technical terms

HTTP classifies PUT and DELETE as idempotent by spec; POST is not by default. Payment-grade idempotency adds a client-generated key stored server-side with the first response: replays of the same key return the cached result, and the unique constraint makes even concurrent retries safe.

POST /orders
Idempotency-Key: 8f2c-41d9-...
{ "cartId": 42 }

// client timed out, retried same key ->
// same order id, no second insert, no double charge

Why it appears in interviews

Every API or payments design question converges on retries: a client timeout does not mean the request failed. The server may already have committed. Only idempotency makes “just retry” safe, so interviewers use it to see whether you design for the network or for the happy path.

The common misconception

Checking existence then inserting is not idempotent. The race lives exactly between the check and the insert. Uniqueness must be enforced by storage (unique constraint), not application hope.

Trade-offs & when it hurts

Keys need a retention window (hours to days) and a store; short windows admit duplicates after expiry, long windows cost storage. On non-money paths, sometimes you accept duplicates and dedupe later in analytics. The senior answer states which regime this endpoint is in and who decided.

How to show it in an interview

Land the API-design answer on the constraint vocabulary: “A retry after a timeout must be safe, so the client sends an Idempotency-Key with a 24-hour window, the second call returns the first response, and a unique constraint makes even concurrent replays safe.” Key, window, constraint. Those three words are what the interviewer is grading.

Questions this concept earns

• How would you design a payments API where client retries are guaranteed?
• A user double-submitted an order because the UI froze: where did the design leak?
• The idempotency window expired and the client retries again. What happens, and who owns that outcome?

Related