Idempotency Keys: The API Safety Net You're Probably Not Using

You hit "Submit Order" and the network drops mid-request. Did the charge go through? Should you retry? Without idempotency keys, you're gambling — and your users are the ones losing money.

Idempotency is the property that making the same request multiple times has the same effect as making it once. Idempotency keys are how you enforce that at the API layer, and every API that processes payments, sends emails, or creates resources should implement them.

How Idempotency Keys Work

The client generates a unique key (usually a UUID) and attaches it to the request as a header. The server stores the key alongside the result. If the same key arrives again — from a retry after a timeout, a double-click, or a network flap — the server returns the cached result instead of re-processing.

POST /v1/charges
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{ "amount": 4999, "currency": "usd", "source": "tok_visa" }

The server sees this key for the first time → processes the charge → stores { key: "550e...", status: 200, body: { id: "ch_abc", ... } }.

If the same request arrives again within the key's TTL, the server looks up the key, finds the stored result, and returns it — no second charge.

Implementing Idempotency Keys on the Server

Here's a minimal Node.js/Express implementation using Redis as the key store:

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

const app = express();
const client = redis.createClient();
await client.connect();

const IDEMPOTENCY_TTL = 60 * 60 * 24; // 24 hours

app.use(express.json());

async function idempotencyMiddleware(req, res, next) {
  const key = req.headers['idempotency-key'];

  // No key provided — treat as non-idempotent (allow through)
  if (!key) return next();

  // Validate key format
  const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
  if (!UUID_REGEX.test(key)) {
    return res.status(400).json({ error: 'Invalid Idempotency-Key format. Use UUID v4.' });
  }

  const cacheKey = `idempotency:${req.path}:${key}`;
  const cached = await client.get(cacheKey);

  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 client.setEx(
        cacheKey,
        IDEMPOTENCY_TTL,
        JSON.stringify({ status: res.statusCode, body })
      );
    }
    return originalJson(body);
  };

  next();
}

app.post('/v1/charges', idempotencyMiddleware, async (req, res) => {
  // Your charge processing logic here
  const charge = await processCharge(req.body);
  res.status(201).json(charge);
});

The Client Side: Generating and Retrying

On the client, generate a fresh UUID per logical operation, not per HTTP request. The same UUID must be reused on retries:

import uuid
import time
import httpx

def create_charge(amount: int, currency: str, source: str, max_retries: int = 3):
    """Create a charge with automatic idempotent retry logic."""
    idempotency_key = str(uuid.uuid4())  # one key per charge attempt

    headers = {
        "Content-Type": "application/json",
        "Idempotency-Key": idempotency_key,
    }
    payload = {"amount": amount, "currency": currency, "source": source}

    for attempt in range(max_retries):
        try:
            response = httpx.post(
                "https://api.example.com/v1/charges",
                json=payload,
                headers=headers,
                timeout=10.0,
            )
            response.raise_for_status()
            return response.json()

        except (httpx.TimeoutException, httpx.ConnectError) as e:
            if attempt == max_retries - 1:
                raise
            wait = 2 ** attempt  # exponential backoff: 1s, 2s, 4s
            print(f"Request failed ({e}), retrying in {wait}s with same key...")
            time.sleep(wait)

        except httpx.HTTPStatusError as e:
            # Don't retry 4xx errors — they're client mistakes
            if 400 <= e.response.status_code < 500:
                raise
            # Retry 5xx server errors with same key
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

Common Mistakes to Avoid

New key on every retry. This defeats the purpose — each new key is a new operation from the server's perspective. Generate once, reuse on all retries for that operation.

Scope the key to the endpoint. A key used for POST /charges should not collide with one used for POST /refunds. Prefix your cache keys with the route.

Too short a TTL. If a client retries 25 hours later because of a delayed job, a 1-hour TTL means they get double-charged. 24 hours is a reasonable baseline for payment operations; some systems go to 7 days.

Accepting idempotency keys on GET requests. GET requests are already idempotent by definition. Only apply this pattern to state-mutating operations: POST, PUT, PATCH, DELETE.

Testing Idempotency

Don't just test the happy path. Verify that:

Sending the same key twice returns identical responses (including id fields)
Sending the same key with a different body returns a 422 Unprocessable Entity or 409 Conflict (the key is bound to the original request)
After TTL expiry, a reused key creates a new operation

Getting idempotency right takes a bit of upfront work, but it's the difference between an API that's safe to call from unreliable networks and one that silently duplicates orders. If you're building or testing APIs and want a workspace that helps you inspect retry behaviour, response caching, and request histories in one place, APIKumo lets you replay requests with the same headers — making it easy to verify your idempotency implementation actually holds under repeat calls.