Idempotency

1What Idempotency Actually Means

An operation is idempotent if performing it multiple times has the same effect as performing it once. This is a statement about effect on state, not about the response body being identical byte-for-byte.

DELETE /orders/42   -> first call: order deleted, 204
                    -> second call: order already gone, 404 (or 204 again)
                    -> EITHER response is fine — the STATE is identical after 1 or N calls

Idempotency matters because networks are unreliable: a client sends a request, the server processes it successfully, but the response is lost (timeout, connection reset, proxy hiccup) before the client sees it. The client, unable to distinguish "my request never arrived" from "it arrived and succeeded but the reply got lost," has exactly one safe move: retry. Idempotency is what makes that retry harmless instead of catastrophic.

2Which HTTP Methods Are Idempotent by Specification

This table is a specification promise, not an automatic property of your code — see Under the Hood for exactly how a naive PUT handler can quietly violate it.

3Why PATCH Is the Dangerous Middle Case

// Idempotent PATCH — absolute assignment
PATCH /accounts/1  { "status": "active" }
// running this 1 time or 100 times leaves status="active" either way

// NON-idempotent PATCH — relative operation disguised as a patch
PATCH /accounts/1  { "balance_delta": +50 }
// running this once: balance += 50
// running this twice (a retried request): balance += 100 — DOUBLE CHARGED

The syntax looks the same (a PATCH with a JSON body); the semantics are opposite. This is precisely the case idempotency keys (section 4) exist to fix — you cannot make balance_delta idempotent by construction without changing the API, but you can make retrying the same balance_delta request safe.

4Idempotency Keys

For POST (and any operation with delta/relative semantics), the client generates a unique key — typically a UUID — and sends it with the request:

POST /payments
Idempotency-Key: 7b9e6e2c-3f1a-4c9a-9e2b-1a2b3c4d5e6f
Content-Type: application/json

{ "amount_cents": 4999, "account_id": "acct_88" }

Server-side contract:

1. Look up the key in an idempotency store.
2. If found AND the stored request matches this one -> return the STORED response. Do not re-run the handler.
3. If found AND the stored request does NOT match (same key, different body) -> 422/409, this is a client bug (key reuse).
4. If not found -> run the handler, store {key, request_fingerprint, response, status} atomically with the effect, THEN return the response.

async function handleWithIdempotency(key: string, body: unknown, handler: () => Promise<Response>) {
  const existing = await store.get(key);
  if (existing) {
    if (existing.fingerprint !== fingerprint(body)) {
      throw new ConflictError("idempotency key reused with a different request body");
    }
    return existing.response; // replay — handler never runs again
  }
  return await runInTransaction(async (tx) => {
    const response = await handler();          // the actual side effect: charge card, create order, etc.
    await store.put(tx, key, fingerprint(body), response); // SAME transaction — see Under the Hood
    return response;
  });
}

The retried request never reaches the "real" logic a second time — it's intercepted and answered from the store. This is the mechanism that turns a non-idempotent POST /payments into something safe to retry blindly.

5Where the Key Comes From and Its Scope

• Client-generated, not server-generated — the whole point is the client can retry with the same key without a round trip to obtain one first.
• Scoped, usually per API credential/account — the same UUID from two different customers must not collide.
• Given an expiry — stores typically retain keys for 24 hours to a few days, not forever; a legitimate new payment with an accidentally-reused key from a week ago should succeed, not be replayed as ancient stale state.

Idempotency-Key: <uuid>              -- client generates, sends verbatim
Store key = hash(account_id + ":" + idempotency_key)
Store TTL = 24h (typical; document your own)

6Natural Idempotency vs. Enforced Idempotency

Two different techniques solve two different shapes of the problem:

Natural idempotency — design the operation itself so repeating it is a no-op, no key needed:

PUT /users/42/roles/admin     -- "ensure user 42 has role admin" — repeat freely
DELETE /users/42/roles/admin  -- "ensure user 42 lacks role admin" — repeat freely

Enforced idempotency (idempotency keys) — the operation is inherently a delta or a creation event (POST /payments, POST /orders) and cannot be redesigned as a "set" operation without losing meaning (you cannot "PUT the state of having charged $50" — the charge is the event).

Prefer natural idempotency wherever the domain allows it — it needs no store, no key management, no TTL policy, and works for every client automatically instead of only clients disciplined enough to send keys.

7Client-Side Retry Strategy

Idempotency keys only pay off paired with a sane client retry policy:

async function postWithRetry(body: unknown, maxAttempts = 3): Promise<Response> {
  const key = crypto.randomUUID(); // ONE key for the whole retry sequence
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fetch("/payments", {
        method: "POST",
        headers: { "Idempotency-Key": key },
        body: JSON.stringify(body),
      });
    } catch (e) {
      if (attempt === maxAttempts) throw e;
      await sleep(backoff(attempt)); // exponential backoff, not immediate retry
    }
  }
  throw new Error("unreachable");
}

The key is generated once outside the loop, not per attempt — generating a fresh key on each retry defeats the entire mechanism, because the server sees each attempt as a brand-new, never-seen request.

BROKEN (two separate steps):
  1. charge the card                     <-- succeeds
  2. crash / process killed / network blip
  3. idempotency record never written
  4. client, having gotten no response, retries with the SAME key
  5. lookup finds nothing (step 3 never happened) -> handler runs AGAIN -> double charge

BEGIN;
  INSERT INTO charges (id, account_id, amount_cents) VALUES ($1, $2, $3);
  INSERT INTO idempotency_keys (key, account_id, fingerprint, response_body, status_code)
    VALUES ($4, $2, $5, $6, $7);
COMMIT;

1. INSERT idempotency_keys(key, status='processing') -- reserve the key FIRST, before the side effect
2. call the external payment processor                -- the actual non-transactional effect
3. UPDATE idempotency_keys SET status='completed', response=... WHERE key=$1

⚠️ Common Pitfalls

1. Generating a new idempotency key on every retry attempt. As shown in section 7, this defeats the mechanism completely — each "retry" looks like a fresh, unique request to the server.
2. Writing the idempotency record in a separate transaction (or a different datastore) from the effect. This is the exact race condition detailed in Under the Hood — the two can get out of sync under a crash.
3. Treating PATCH as automatically idempotent. As section 3 shows, a delta-style PATCH body is exactly as dangerous to retry blindly as POST — it needs the same key-based protection.
4. No fingerprint check on key reuse. Silently replaying a stored response for a different request body (because only the key was checked) hides real client bugs as successful-looking responses.
5. No TTL on stored keys — or too short a TTL. Forever-retained keys grow the store unboundedly; too-short a TTL lets a legitimately delayed retry (a mobile client reconnecting after being offline for an hour) fall through and double-execute.
6. Assuming natural idempotency where the domain doesn't have it. POST /orders cannot be made naturally idempotent by wishing — creating "the same order" twice by definition creates two orders unless a key (or a natural dedup field, like a client-supplied order UUID used as the primary key) makes the second attempt a no-op.
7. Only documenting idempotency keys for payment endpoints. Any POST with a real-world side effect that's expensive or irreversible to duplicate (sending an email, provisioning a resource, charging a card) benefits from the same pattern — payments are just the case everyone remembers.

📋 Quick Reference

Idempotent by spec        GET, PUT, DELETE, HEAD, OPTIONS
Not idempotent by spec    POST         -- and PATCH, conditionally (see below)
PATCH is idempotent       IFF it's an absolute assignment ({"status":"active"})
PATCH is NOT idempotent   IFF it's a delta/relative op ({"balance_delta": +50})

Idempotency-Key: <client-generated UUID>, ONE key per logical retry sequence
Server contract:
  found + fingerprint matches    -> replay stored response, don't re-run handler
  found + fingerprint mismatches -> 409/422, key reuse is a client bug
  not found                      -> run handler; write {key, fingerprint, response}
                                     in the SAME transaction as the effect

Natural idempotency   PUT/DELETE on a well-designed resource — no store needed, prefer this
Enforced idempotency  idempotency-key store — needed for POST / delta PATCH

Distributed effect    reserve key (status=processing) -> call external system -> mark completed
Client retry          generate key ONCE outside the retry loop; exponential backoff

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: api_idempotency_theory.md · generated by tools/build_lessons.py