Idempotency Keys: The One API Pattern That Prevents Duplicate Payments (and Worse)

You hit "Submit Order" and nothing happens. The spinner just spins. Is it processing? Did the request get lost? You click again.

If the API on the other end does not implement idempotency, you just placed two orders. Maybe two charges to your card. This is a solved problem — and the solution is simpler than you think.

What Is Idempotency?

An operation is idempotent if doing it multiple times produces the same result as doing it once. GET requests are naturally idempotent — fetching a resource does not change it. DELETE is also idempotent in practice. The trouble is POST and PATCH: create an order twice, and you get two orders.

An idempotency key is a client-generated unique identifier (usually a UUID) that you send with a mutating request. The server stores this key with the result. If the same key arrives again — whether due to a retry, a network blip, or an impatient user — the server returns the cached result instead of executing the operation again.

Implementing Idempotency on the Server

Here is a minimal Express implementation backed by Redis:

const express = require("express");
const redis = require("ioredis");
const { v4: uuidv4 } = require("uuid");

const app = express();
const cache = new redis();
app.use(express.json());

// TTL for idempotency records: 24 hours
const IDEMPOTENCY_TTL = 86400;

async function idempotencyMiddleware(req, res, next) {
  const key = req.headers["idempotency-key"];
  if (!key) return next(); // optional on GET/DELETE

  const cached = await cache.get(`idem:${key}`);
  if (cached) {
    const { status, body } = JSON.parse(cached);
    return res.status(status).json(body);
  }

  // Intercept the response to cache it
  const originalJson = res.json.bind(res);
  res.json = async (body) => {
    if (res.statusCode < 500) {
      await cache.setex(
        `idem:${key}`,
        IDEMPOTENCY_TTL,
        JSON.stringify({ status: res.statusCode, body })
      );
    }
    return originalJson(body);
  };

  next();
}

app.post("/orders", idempotencyMiddleware, async (req, res) => {
  // Actual order creation logic here
  const order = { id: uuidv4(), item: req.body.item, status: "created" };
  res.status(201).json(order);
});

app.listen(3000);

The key points:

• Cache keyed by idem:${idempotency-key} (namespace to avoid collisions)
• Do not cache 5xx responses — those are server errors the client should retry fresh
• Set a reasonable TTL (24h is Stripe's default)

The Client Side

Clients should generate a new key per logical operation, not per HTTP request. A retry of the same operation reuses the same key:

import uuid
import httpx
import time

def create_order(item: str, max_retries: int = 3) -> dict:
    idempotency_key = str(uuid.uuid4())  # Generated once per operation

    for attempt in range(max_retries):
        try:
            response = httpx.post(
                "https://api.example.com/orders",
                json={"item": item},
                headers={"Idempotency-Key": idempotency_key},
                timeout=10,
            )
            response.raise_for_status()
            return response.json()
        except httpx.TimeoutException:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

# Safe to call even if the network drops mid-flight
order = create_order("Pro Subscription")

Notice that idempotency_key is created before the loop. Every retry sends the same key. If the first request succeeded but the response was lost in transit, the second request returns the original result from cache — no duplicate charge.

What to Use as the Key

Use a UUIDv4 generated client-side. Some APIs let you derive the key from the request content (content-addressed), but that is error-prone — two different users ordering the same item would collide. Random UUIDs are safe.

Store the key alongside your local pending order record:

INSERT INTO pending_orders (idempotency_key, item, created_at)
VALUES ($1, $2, NOW())
ON CONFLICT (idempotency_key) DO NOTHING;

This lets you recover the key after a crash and retry safely.

Common Mistakes

Generating a new key per retry defeats the entire purpose. The server sees each request as fresh and executes it again.

Not handling key collisions — vanishingly rare with UUID4, but you should reject reused keys with mismatched request bodies. Stripe returns a 422 if the body does not match the original.

Caching error responses — if you cache a 400 Bad Request, the client can never fix their payload and retry. Only cache success (2xx) and stable client errors that do not depend on transient state.

Testing Idempotency

Replay the same request twice and assert the response bodies are identical and only one side-effect occurred:

it("does not double-charge on retry", async () => {
  const key = randomUUID();
  const headers = { "Idempotency-Key": key };

  const r1 = await post("/orders", { item: "Subscription" }, headers);
  const r2 = await post("/orders", { item: "Subscription" }, headers);

  expect(r1.body.id).toEqual(r2.body.id);
  expect(await db.count("orders")).toBe(1); // Only one order created
});

---

Idempotency is table stakes for any API that handles money, inventory, or state you cannot easily undo. The pattern is straightforward: one UUID per operation, stored server-side with its result, returned verbatim on replay.

If you are building or testing APIs and want to validate idempotency behaviour before it hits production, APIKumo lets you replay saved requests with the same headers and diff the responses — making it easy to confirm your implementation works correctly without writing a test harness from scratch.