Idempotency Explained: Safe Retries and Idempotency Keys

• A new key on every attempt

  Generating the key inside the retry loop makes every retry a new request, and the protection is gone. Create the key once per operation, store it with the pending operation, and reuse it across retries, process restarts and page reloads. Stripe's guide warns that a new key can start a second operation.

• Check the key, then save it, in two steps

  Two duplicates that arrive together both read no record for the key, both do the work, and the customer is charged twice. Claim the key first, in one atomic step that a unique constraint decides, mark it in progress, and only the request that won the claim does the work. The other gets 409.

• A done marker written before the work is done

  Skip-if-exists is only idempotent if the marker means the whole job finished. If a later step fails, a re-run skips a half-done job forever, as this repo's merge script once did. Write the marker in the same transaction as the work, or settle everything that can fail before the first write.

• Treating a 500 as permission to try again fresh

  A 500 is indeterminate: the operation may have had side effects. Stripe's guide says not to retry with a new key until you have resolved the original outcome, and to stop retrying an unresolved operation after the 24-hour window and reconcile it instead.

• What I'd change here: one key per contact message

  The form could create crypto.randomUUID() once per filled-in message, send it with the POST, and clear it only after success. The route would pass it to emails.send as idempotencyKey, which Resend keeps for 24 hours, so a second press after a lost reply returns the first result instead of a second email. The error copy should also say the message may have been sent.

1. 1

   Save the server as server.mjs and start it with node server.mjs in its own terminal. It prints the number of charges after each one.

   // server.mjs: a toy payments API. Each charge takes 1.5 s. With an
   // Idempotency-Key header, the first result is stored and replayed.
   import { createHash } from "node:crypto";
   import http from "node:http";
   
   const charges = [];
   const keys = new Map(); // key -> { fingerprint, done, status, body }
   const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
   
   function reply(res, status, body, headers = {}) {
     res.writeHead(status, { "Content-Type": "application/json", ...headers });
     res.end(JSON.stringify(body) + "\n");
   }
   
   http
     .createServer(async (req, res) => {
       if (req.method === "GET") return reply(res, 200, { charges: charges.length });
       let raw = "";
       for await (const chunk of req) raw += chunk;
       const key = req.headers["idempotency-key"];
       const fingerprint = createHash("sha256").update(raw).digest("hex");
       if (key) {
         const seen = keys.get(key);
         if (seen && seen.fingerprint !== fingerprint)
           return reply(res, 422, { error: "key reused with a different body" });
         if (seen && !seen.done)
           return reply(res, 409, { error: "a request with this key is in progress" });
         if (seen) return reply(res, seen.status, seen.body, { "Idempotent-Replayed": "true" });
         keys.set(key, { fingerprint, done: false }); // claim the key BEFORE the work
       }
       await sleep(1500); // the slow part, like a call to a card network
       const charge = { id: `ch_${charges.length + 1}`, body: raw };
       charges.push(charge);
       if (key) keys.set(key, { fingerprint, done: true, status: 201, body: charge });
       console.log("charges so far:", charges.length);
       reply(res, 201, charge);
     })
     .listen(4242, "127.0.0.1", () => console.log("listening on 127.0.0.1:4242"));

   Copy
2. 2

   Lose a reply on purpose. curl -m 1 gives up after one second, before the 1.5-second charge answers, so it prints a timeout (error 28) although the server charged. Retry the same POST and read the count: 2 charges for one order.

   curl -sS -m 1 -X POST http://127.0.0.1:4242/charges -d 'order=A-1'
   curl -sS -X POST http://127.0.0.1:4242/charges -d 'order=A-1'
   curl -sS http://127.0.0.1:4242/charges

   Copy
3. 3

   Do it again with an idempotency key made once, before the first attempt. The first call times out again; the retry gets the stored 201 with Idempotent-Replayed: true, and the count goes up by one, not two.

   KEY=$(node -p "crypto.randomUUID()")
   curl -sS -m 1 -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=B-1'
   sleep 1
   curl -sS -i -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=B-1'
   curl -sS http://127.0.0.1:4242/charges

   Copy
4. 4

   Send a duplicate while the first request is still running. The duplicate prints 409 at once; the original prints 201 when it finishes.

   KEY=$(node -p "crypto.randomUUID()")
   curl -sS -w '%{http_code}\n' -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=C-1' &
   sleep 0.2
   curl -sS -w '%{http_code}\n' -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=C-1'
   wait

   Copy
5. 5

   In the same terminal, reuse that key with a different body. The server refuses with 422, as the IETF draft suggests, instead of replaying an answer to a different request.

   curl -sS -w '%{http_code}\n' -X POST http://127.0.0.1:4242/charges -H "Idempotency-Key: $KEY" -d 'order=C-2'

   Copy
6. 6

   Now natural idempotency in SQLite. The upsert inserts once (changes 1) and does nothing the second time (changes 0). Subtracting twice leaves 10; setting 11 twice leaves 11.

   sqlite3 :memory: <<'SQL'
   CREATE TABLE processed (message_id TEXT PRIMARY KEY);
   CREATE TABLE stock (sku TEXT PRIMARY KEY, qty INTEGER);
   INSERT INTO stock VALUES ('mug', 12);
   -- a redelivered message, handled twice
   INSERT INTO processed VALUES ('msg-42') ON CONFLICT (message_id) DO NOTHING;
   SELECT changes();
   INSERT INTO processed VALUES ('msg-42') ON CONFLICT (message_id) DO NOTHING;
   SELECT changes();
   -- add-by-amount twice, then set-a-value twice
   UPDATE stock SET qty = qty - 1 WHERE sku = 'mug';
   UPDATE stock SET qty = qty - 1 WHERE sku = 'mug';
   SELECT qty FROM stock;
   UPDATE stock SET qty = 11 WHERE sku = 'mug';
   UPDATE stock SET qty = 11 WHERE sku = 'mug';
   SELECT qty FROM stock;
   SQL

   Copy
7. 7

   Stop the server with Ctrl+C in its terminal. It keeps everything in memory, so nothing is left behind.

From: 9. WebSocket vs SSE vs Long Polling: Real-Time Updates Explained · 7. System Design Case Study Example: Designing This Website

1. 1.Why is DELETE idempotent even though a second call may answer differently?Show the answer

   Answer:Idempotency is about the intended effect on the server, not the response. After one DELETE or two, the resource is gone; RFC 9110 says the response to a repeat might differ.

2. 2.What does a server store for each idempotency key, and when?Show the answer

   Answer:A fingerprint of the body, the state of the work, and the status and body it answered. It claims the key as in progress before doing the work, so a duplicate in flight gets 409, and saves the result when the work ends.

3. 3.A deploy script appends to .env with >>. What happens when the deploy runs again, and what is the fix?Show the answer

   Answer:Every line appears twice, and the file grows on each run. Rewrite the whole file with >, as this site's deploy does with cat > .env, so each run leaves the same file.

4. 4.When is natural idempotency enough, and when do you need a key?Show the answer

   Answer:When the request names the resource and carries its full state, as with PUT, a set or an upsert on a natural unique key, repeats converge. When each request creates something new, such as a charge or an email, only a key the client chose can tell a retry from a new request.

• idempotency key design for APIs
• the idempotent consumer pattern for message queues
• reliable webhook delivery design