Idempotency Keys

You click "Pay" on an e-commerce site. The browser sends the payment request. The spinner appears. Then your network drops. The page shows an error: "Something went wrong."

Did the payment actually go through? You do not know. The server might have charged your card successfully and the failure happened when sending the response back. Or the server never received the request at all.

If you click "Pay" again, you might be charged twice. If you do not, you might not be charged at all. This uncertainty is the fundamental problem idempotency keys solve.

An idempotency key is a unique identifier that the client attaches to a request. The server uses it to guarantee that the same request, if sent multiple times, produces the same result, and the side effect happens only once. Stripe popularized this pattern: every payment API call accepts an Idempotency-Key header. If you retry the same key, Stripe returns the cached response from the first attempt instead of charging again.

Stripe processes over 250 million API calls per day. Their engineering blog reports that roughly 0.1% of those calls are retries with idempotency keys, preventing around 250,000 potential duplicate charges daily. That is the scale of the problem.

The client generates a unique key (typically a UUID) and includes it in the request:

POST /api/charges
Idempotency-Key: idem_abc123xyz
Content-Type: application/json

{ "amount": 5000, "currency": "usd", "customer": "cus_123" }

The server's logic:

async function handleCharge(req) {
  const idempotencyKey = req.headers['idempotency-key'];

  // 1. Check if this key has been seen before
  const cached = await redis.get(`idem:${idempotencyKey}`);
  if (cached) {
    return JSON.parse(cached); // Return cached response
  }

  // 2. Lock the key to prevent concurrent duplicates
  const locked = await redis.set(
    `idem:lock:${idempotencyKey}`, '1', 'NX', 'EX', 30
  );
  if (!locked) {
    return { status: 409, error: 'Request in progress' };
  }

  // 3. Process the charge (first time)
  const result = await stripe.charges.create(req.body);

  // 4. Cache the response with the key (TTL: 24 hours)
  await redis.setex(
    `idem:${idempotencyKey}`, 86400, JSON.stringify(result)
  );

  return result;
}

On retry (same key, same request): The server finds the cached response and returns it immediately. No second charge.

On different request (different key): New key, new charge. Each unique operation gets a unique idempotency key.

Critical rules:

• The same key with different request bodies should return an error (the key is bound to one specific request)
• Keys should expire after a reasonable period (24-48 hours)
• The key lookup and the business operation must be atomic (to avoid race conditions from concurrent retries)
• Store the request fingerprint (hash of the body) alongside the key so you can detect mismatched retries