What is idempotency and how do you implement it in an API?

Networks are unreliable. A client may send a request, lose the response and retry. If the server processed the first attempt, a naive retry can charge a card twice or create two orders. Idempotency makes the retry safe by recording the key and replaying the original result.

const key = req.get("Idempotency-Key");
const fingerprint = hashBody(req.body);
const existing = await idempotency.find(key);

if (existing) {
  if (existing.fingerprint !== fingerprint) {
    return res.status(422).json({ error: "key_reused_with_different_body" });
  }
  return res.status(existing.status).json(existing.body);
}

const result = await createOrder(req.body);
await idempotency.save(key, fingerprint, result);
res.status(201).json(result);

Implementation requirements

• The key is scoped to a client or tenant, not global
• The record and the business change should commit atomically or be recoverable
• Store the response so retries return the same status and body
• Handle concurrent attempts with a uniqueness constraint or lock, not a read-then-write race
• Expire keys after a window longer than the client retry policy
• Do not treat implicit retries in a proxy or queue as safe without this protection

PUT is naturally idempotent when it replaces the full resource with a known representation. PATCH may or may not be, depending on whether it applies a delta or sets a value. DELETE is idempotent by intent, though the response code can differ on a second call.