Idempotency Keys: Safe Retries for POST Requests

A customer taps "Pay ₹2,499". The request reaches your server, the payment succeeds – and the mobile network drops before the response arrives. The app can't tell whether the payment happened. If it retries, the customer may be charged twice; if it doesn't, the order may never be confirmed. Idempotency keys, popularised by Stripe and now an IETF draft standard, make POST requests safe to retry.

Implementation

// server.js
import express from 'express';
import { createHash } from 'node:crypto';

const app = express();
app.use(express.json());

const payments = [];
const idempotency = new Map();          // key → { fingerprint, status, body }  (Redis/DB with a 24 h TTL in production)
const fingerprint = (req) => createHash('sha256').update(JSON.stringify(req.body)).digest('hex');

app.post('/api/payments', (req, res) => {
  const key = req.get('Idempotency-Key');
  if (!key) return res.status(400).json({ error: 'Idempotency-Key header is required for payments' });

  const seen = idempotency.get(key);
  if (seen) {
    if (seen.fingerprint !== fingerprint(req)) {
      return res.status(422).json({ error: 'This Idempotency-Key was already used with a different request' });
    }
    return res.status(seen.status).set('Idempotency-Replayed', 'true').json(seen.body);   // replay, don't redo
  }

  // … charge the card exactly once …
  const payment = { id: `pay_${payments.length + 1}`, amount: req.body.amount, currency: req.body.currency, status: 'succeeded' };
  payments.push(payment);

  idempotency.set(key, { fingerprint: fingerprint(req), status: 201, body: payment });
  res.status(201).json(payment);
});

app.get('/api/payments', (req, res) => res.json({ count: payments.length, payments }));

app.listen(process.env.PORT ?? 3000);

$ curl -X POST http://localhost:3000/api/payments -H 'Content-Type: application/json' -H 'Idempotency-Key: 7f9c2b1e-checkout-1001' -d '{"amount":249900,"currency":"INR"}'
HTTP/1.1 201 Created
Content-Type: application/json; charset=utf-8

{
  "id": "pay_1",
  "amount": 249900,
  "currency": "INR",
  "status": "succeeded"
}

$ curl -X POST http://localhost:3000/api/payments -H 'Content-Type: application/json' -H 'Idempotency-Key: 7f9c2b1e-checkout-1001' -d '{"amount":249900,"currency":"INR"}'
HTTP/1.1 201 Created
Idempotency-Replayed: true
Content-Type: application/json; charset=utf-8

{
  "id": "pay_1",
  "amount": 249900,
  "currency": "INR",
  "status": "succeeded"
}

$ curl -X POST http://localhost:3000/api/payments -H 'Content-Type: application/json' -H 'Idempotency-Key: 7f9c2b1e-checkout-1001' -d '{"amount":999,"currency":"INR"}'
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8

{
  "error": "This Idempotency-Key was already used with a different request"
}

$ curl http://localhost:3000/api/payments
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "count": 1,
  "payments": [
    {
      "id": "pay_1",
      "amount": 249900,
      "currency": "INR",
      "status": "succeeded"
    }
  ]
}

The retry got exactly the same 201 response – with Idempotency-Replayed: true – and the payment list still has one payment. Reusing the key for a different amount was rejected instead of silently returning the old payment.

The client side

import { randomUUID } from 'node:crypto';     // or crypto.randomUUID() in browsers

async function pay(amount) {
  const key = randomUUID();                    // ONE key per logical payment, reused for every retry
  for (let attempt = 1; attempt <= 3; attempt++) {
    try {
      const res = await fetch('/api/payments', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json', 'Idempotency-Key': key },
        body: JSON.stringify({ amount, currency: 'INR' }),
        signal: AbortSignal.timeout(5000),
      });
      if (res.status < 500) return res.json(); // success or a client error – don't retry 4xx
    } catch { /* timeout or network error: retry with the same key */ }
  }
  throw new Error('Payment status unknown – check later');
}

Production rules

Practice

Summary