Idempotency Keys: The Safety Net Every Mutation API Needs

Network failures happen. A user clicks "Pay" and their connection drops mid-request. Your retry logic fires. The charge goes through twice. Your support inbox fills up.

Idempotency keys are the standard fix — and yet they're one of the most under-used patterns in API design. This article explains what they are, how to implement them correctly on both the client and server side, and what can go wrong when you get it wrong.

What Is an Idempotency Key?

An idempotency key is a unique identifier — typically a UUID — that a client sends with a mutating request. If the server receives two requests with the same key, it processes the operation once and returns the same response for all subsequent duplicates.

The concept is simple: safe to retry without side effects.

Stripe, PayPal, and most serious payment APIs require idempotency keys. Here's what a typical request looks like:

POST /v1/charges
Idempotency-Key: a8098c1a-f86e-11da-bd1a-00112444be1e
Content-Type: application/json

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

Generating Idempotency Keys on the Client

Always generate the key before making the request, not after a failure. If you generate a new key on retry, you lose the protection entirely.

// Node.js example
import { randomUUID } from 'crypto';

async function chargeCustomer(amount, source) {
  // Generate ONCE before the first attempt
  const idempotencyKey = randomUUID();

  const MAX_RETRIES = 3;
  let lastError;

  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    try {
      const response = await fetch('https://api.example.com/v1/charges', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey, // Same key on every retry
        },
        body: JSON.stringify({ amount, source }),
      });

      if (!response.ok) {
        // Don't retry on client errors (4xx)
        if (response.status >= 400 && response.status < 500) {
          throw new Error(`Client error: ${response.status}`);
        }
        throw new Error(`Server error: ${response.status}`);
      }

      return await response.json();
    } catch (err) {
      lastError = err;
      // Exponential backoff between retries
      await new Promise(r => setTimeout(r, 2 ** attempt * 100));
    }
  }

  throw lastError;
}

Implementing Idempotency on the Server

Server-side, you need to:

1. Store the key alongside the result after the operation completes
2. Check for the key before processing any new request
3. Return the cached result if the key was seen before

Here's a minimal Python/FastAPI implementation using Redis:

import json
import redis
from fastapi import FastAPI, Header, HTTPException
from pydantic import BaseModel

app = FastAPI()
cache = redis.Redis(host='localhost', port=6379, decode_responses=True)

TTL_SECONDS = 86400  # Store keys for 24 hours

class ChargeRequest(BaseModel):
    amount: int
    currency: str
    source: str

@app.post("/v1/charges")
async def create_charge(
    body: ChargeRequest,
    idempotency_key: str = Header(None, alias="Idempotency-Key")
):
    if not idempotency_key:
        raise HTTPException(status_code=400, detail="Idempotency-Key header required")

    cache_key = f"idem:{idempotency_key}"

    # Check for a previous result
    cached = cache.get(cache_key)
    if cached:
        # Return the stored response — 200, not 201
        return json.loads(cached)

    # Process the charge (your actual business logic here)
    result = process_charge(body.amount, body.currency, body.source)

    # Persist the result before returning it
    cache.setex(cache_key, TTL_SECONDS, json.dumps(result))

    return result

Critical detail: Store the result before responding. If you store after responding, a crash between those two steps leaves you without a record, and the next retry will process the operation again.

What to Watch Out For

Don't scope keys globally forever. Keys should expire. Stripe expires them after 24 hours. Keeping them permanently burns storage and risks key collisions from poorly written clients.

Keys must be scoped per operation type. A key for a charge should not conflict with a key for a refund. Prefix your cache keys: charge:uuid, refund:uuid.

Return 200 for replays, not 201. When returning a cached result, use the same status code as the original response — not a new one. Some clients distinguish 200 OK from 201 Created for important flow logic.

Validate the request body hasn't changed. If the same key arrives with a different payload, that's a bug in the client. Return a 422 Unprocessable Entity with a clear error message rather than silently ignoring the mismatch.

# Add body fingerprint check
import hashlib

cached_data = json.loads(cached)
request_hash = hashlib.sha256(body.json().encode()).hexdigest()

if cached_data.get('_request_hash') != request_hash:
    raise HTTPException(
        status_code=422,
        detail="Idempotency key reused with a different request body"
    )

Testing Your Idempotency Implementation

Before shipping, verify three scenarios manually:

1. First request — processes normally, stores result, returns 201
2. Duplicate request — returns cached result, returns 200, no second charge
3. Same key, different body — returns 422 with a clear error

With APIKumo, you can build a test collection that chains these three requests in sequence, uses variables to share the same idempotency key across steps, and asserts on status codes and response bodies in post-processors — making idempotency regression testing a one-click run rather than a manual checklist.

The Bottom Line

Idempotency keys are a small implementation cost that buys you enormous reliability. Add them to every endpoint that creates, updates, or deletes data. Require them from clients on anything that involves money or irreversible state changes. Your on-call rotation will thank you.