Idempotency & Safe Retries

The two-generals problem in every network call

The problem idempotency solves is the two generals nature of a network call. A client sends "submit payment," the server processes it, and then the response is lost to a timeout or a dropped connection. The client does not know whether the charge happened. If it retries naively, you double-charge. If it gives up, you might drop a real payment. Idempotency lets the client retry safely and get the same result every time.

Start with what HTTP already gives you. GET, PUT, and DELETE are idempotent by definition: sending them twice leaves the server in the same state as sending them once (PUT sets a value; setting it twice is the same value; DELETE twice still ends deleted). POST and PATCH are not idempotent, because "create" or "add $50" applied twice does two things. Those are exactly the methods that need explicit help.

The idempotency key

The client generates a unique key (a UUID) for the logical operation and sends it, typically as an Idempotency-Key header. The server, on first receipt, processes the request and stores the full response keyed by that key with a TTL (24 hours is a common window). On any retry with the same key, the server does not reprocess; it returns the stored response.

The subtle, commonly-missed detail: store the response, not just a boolean "seen it" flag. Two things force this. First, the retry must get the actual result (the charge id, the status), not just "yes." Second, concurrency: the original request and the retry can arrive at the same instant. You need a way for the second one to either wait for the first to finish or detect an in-flight operation, so they converge on one answer instead of both charging. In practice you insert the key into a store with a unique constraint (a Redis SETNX or a unique DB row) before doing work; the loser of that race waits and returns the winner's stored response.

From at-least-once to effectively-once

Networks and queues give you at-least-once delivery: a message can arrive more than once. Idempotency (deduplication on a key) is what turns at-least-once into effectively-once processing. You cannot get true exactly-once over an unreliable network; you get at-least-once plus idempotent handling, which is behaviorally equivalent and is what payment systems actually do.

The same pattern extends beyond synchronous APIs. Webhooks should carry an event id so the receiver can dedupe redelivered events, and message-queue consumers should dedupe on a key so a redelivered Kafka or SQS message is processed once.

Interview nuance: interviewers push on the concurrency case. "Store a flag" is the answer that fails; "store the response behind a unique-constraint insert so concurrent duplicates converge" is the one that passes.

Recap: give mutating requests a client-generated idempotency key, store the full response behind a unique constraint with a TTL, and return it on any retry so at-least-once delivery becomes effectively-once and nobody double-charges.