DEV Community: Mean

Idempotency Keys: The One Pattern That Saves You From Duplicate API Requests

Mean — Tue, 02 Jun 2026 02:59:57 +0000

Network failures are inevitable. A payment request times out. Your client retries. The server processed the original — now your user just got charged twice.

Idempotency keys are the standard solution. They let clients safely retry any request while guaranteeing the server executes it exactly once. Every major payment API (Stripe, Adyen, PayPal) uses them. You should too.

How It Works

The client generates a unique key (typically a UUID) for each logical operation and attaches it to the request — usually as an Idempotency-Key header. The server stores the key alongside the result on first execution. On any retry with the same key, it returns the cached result without re-executing the operation.

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

{
  "amount": 5000,
  "currency": "usd",
  "customer_id": "cus_abc123"
}

If the server returns a 200 OK with the payment result — great. If the network dies before the response arrives, the client retries with the same key and gets the same 200 OK without a second charge.

Implementing Idempotency on the Server Side

Here's a minimal Express implementation backed by Redis:

const express = require('express');
const redis = require('redis');

const app = express();
const client = redis.createClient();
app.use(express.json());

const IDEMPOTENCY_TTL = 86400; // 24 hours

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

  if (!key) return next(); // Optional: enforce for mutating methods only

  const cacheKey = `idempotency:${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('/payments', idempotencyMiddleware, async (req, res) => {
  // Your payment logic here
  const payment = await processPayment(req.body);
  res.status(201).json(payment);
});

Key decisions in this implementation:

Only cache non-5xx responses. A 500 means something went wrong server-side — don't cache the failure, let the client retry and trigger a fresh attempt.
Set a TTL. 24 hours is standard. After expiry, clients should generate a new key rather than retrying the original operation.
Scope the cache key. Prefix with idempotency: (or even per-user: idempotency:{userId}:{key}) to avoid collisions.

Generating Keys on the Client Side

The client is responsible for generating a key per logical operation — not per HTTP request. This distinction matters:

import uuid
import httpx
import time

def charge_customer(amount: int, currency: str, customer_id: str) -> dict:
    # Generate once per operation, persist across retries
    idempotency_key = str(uuid.uuid4())

    for attempt in range(3):
        try:
            response = httpx.post(
                "https://api.example.com/payments",
                headers={"Idempotency-Key": idempotency_key},
                json={
                    "amount": amount,
                    "currency": currency,
                    "customer_id": customer_id
                },
                timeout=10.0
            )
            response.raise_for_status()
            return response.json()
        except (httpx.TimeoutException, httpx.NetworkError):
            if attempt == 2:
                raise
            time.sleep(2 ** attempt)  # Exponential backoff

The same idempotency_key is used across all three retry attempts. If you generated a new UUID on each retry, you'd defeat the purpose entirely.

Edge Cases to Handle

Concurrent requests with the same key. Two retries can arrive simultaneously before the first completes. Use a database lock or Redis SET NX (set-if-not-exists) to hold a "processing" placeholder:

// Atomic lock: only succeeds if key doesn't exist
const locked = await client.set(cacheKey, 'PROCESSING', {
  NX: true,          // Only set if not exists
  EX: 30             // Lock expires in 30s (safety net)
});

if (!locked) {
  // Another request is in-flight — return 409 or wait and retry
  return res.status(409).json({ error: 'Request in progress' });
}

Key conflicts across users. Scope your cache key to the user or API key to prevent one user's key colliding with another's. A UUID is practically collision-free, but defence-in-depth doesn't hurt.

Different request bodies, same key. Treat this as an error. If the stored fingerprint of the original request body doesn't match the retry, return 422 Unprocessable Entity. Some clients reuse keys accidentally; catching this early surfaces bugs.

What to Expose in Your API Docs

Document idempotency clearly:

Which endpoints support (or require) Idempotency-Key
How long keys are retained (the TTL)
What happens on body mismatch
The expected format (UUID v4 is convention)

Tools like APIKumo let you document these headers directly alongside your endpoint specs and test idempotent flows by replaying requests with the same key — useful for verifying your implementation behaves correctly on retries without spinning up a separate test harness.

The Short Version

Client generates a UUID per logical operation
Client sends it as Idempotency-Key on every attempt
Server stores key → result in Redis with a TTL
On retry, server returns the cached result without re-executing
Server-side errors (5xx) are never cached

It's a small addition that eliminates an entire class of data-integrity bugs. If your API handles payments, order creation, or anything with real-world side effects — add idempotency keys before you need them.

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

Mean — Sun, 31 May 2026 03:02:44 +0000

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.

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

Mean — Sat, 30 May 2026 02:21:49 +0000

Network requests fail. Timeouts happen. Clients retry. And without idempotency keys, a single payment request can become three charges.

Idempotency keys are one of those API patterns that's easy to overlook until something goes wrong in production. Here's how they work, when to use them, and how to implement them correctly.

What Is Idempotency?

An operation is idempotent if running it multiple times produces the same result as running it once. GET requests are naturally idempotent — fetching a resource 10 times changes nothing. But POST requests (creating a payment, sending an email, provisioning a server) are not. Each call creates a new thing.

Idempotency keys give POST requests the safety of GET requests. You attach a unique key to the request, and the server uses it to deduplicate repeated calls.

How It Works

The client generates a unique key (typically a UUID) and sends it in a header:

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

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

The server stores the key alongside the result. If the same key arrives again, it returns the cached response instead of re-executing the operation:

First request  → Process payment → Store result → Return 201 + result
Retry request  → Look up key    → Return cached result (no charge)

Implementing Idempotency Keys Server-Side

Here's a minimal implementation in Node.js with Express and Redis:

const express = require('express');
const redis = require('redis');
const app = express();
const redisClient = redis.createClient();
app.use(express.json());

app.post('/payments', async (req, res) => {
  const idempotencyKey = req.headers['idempotency-key'];

  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Idempotency-Key header required' });
  }

  // Check cache first
  const cached = await redisClient.get(`idempotency:${idempotencyKey}`);
  if (cached) {
    return res.status(200).json(JSON.parse(cached));
  }

  // Acquire lock to prevent concurrent duplicate execution
  const lock = await redisClient.set(
    `lock:${idempotencyKey}`, '1', { NX: true, EX: 30 }
  );
  if (!lock) {
    return res.status(409).json({ error: 'Request in progress, retry shortly' });
  }

  try {
    const result = await processPayment(req.body);

    // Cache the result for 24 hours
    await redisClient.setEx(
      `idempotency:${idempotencyKey}`,
      86400,
      JSON.stringify(result)
    );

    return res.status(201).json(result);
  } finally {
    await redisClient.del(`lock:${idempotencyKey}`);
  }
});

Three details matter here:

Cache the full response, not just a flag. The retry needs to receive exactly what the original call returned — same status, same body.

Set a TTL. Keys don't need to live forever. 24–48 hours covers any realistic retry window.

Lock before processing. If two retries arrive simultaneously before either has stored a result, you need a distributed lock (Redis SET NX) to prevent both threads from executing the payment concurrently.

Sending Idempotency Keys as a Client

On the client side, generate a UUID per logical operation — not per HTTP call. If you're retrying, reuse the same key:

import httpx
import uuid

def create_payment(amount: int, currency: str, retries: int = 3) -> dict:
    # Generate ONCE before the retry loop
    idempotency_key = str(uuid.uuid4())

    for attempt in range(retries):
        try:
            response = httpx.post(
                "https://api.example.com/payments",
                json={"amount": amount, "currency": currency},
                headers={"Idempotency-Key": idempotency_key},
                timeout=10.0
            )
            response.raise_for_status()
            return response.json()
        except (httpx.TimeoutException, httpx.HTTPStatusError) as e:
            if attempt == retries - 1:
                raise
            continue  # Retry with the SAME idempotency_key

The critical mistake to avoid: generating a new UUID inside the retry loop. That defeats the entire purpose.

When to Use Idempotency Keys

Use them on any non-idempotent endpoint where duplicate execution causes real harm:

Payment processing — the canonical case
Email and notification sending
Resource provisioning (servers, databases, subscriptions)
Inventory deductions
Financial transfers

Skip them on read-heavy endpoints or operations already naturally idempotent (like PUT with a full resource replacement).

Edge Cases Worth Knowing

Different payload, same key — decide whether to return an error or the cached result. Stripe returns a 422 if the payload doesn't match the original. That's the safer choice and makes bugs visible.

Failure between charging and caching — if your payment processor charges the card but the Redis write fails, a retry will charge again. Use a transactional outbox or write-ahead log to keep charging and caching atomic.

Key namespace by user — prefix keys with a user or account ID to prevent one user's key from colliding with another's in multi-tenant systems.

Testing the Flow

Testing idempotency manually means crafting the right headers, sending the same request twice, and verifying the second call returns a cached response without re-executing. This is where having a proper API client matters. APIKumo lets you save idempotency key headers directly in your request collections, replay requests with the same headers, and inspect response diffs — so you can verify deduplication behavior without juggling curl flags or writing throwaway scripts. If you're building or integrating payment-grade APIs, it's the kind of workflow support that pays for itself the first time you catch a double-charge bug before it ships.

Cursor-Based Pagination: Why OFFSET Is Killing Your API (and How to Fix It)

Mean — Fri, 29 May 2026 05:22:42 +0000

Cursor-based pagination is one of those API design decisions that seems trivial until your dataset grows, users start scrolling fast, and your OFFSET 100000 query brings the database to its knees. If you're still paginating with ?page=2&limit=20, this post is for you.

Why offset pagination breaks

The classic approach looks like this:

SELECT * FROM events
ORDER BY created_at DESC
LIMIT 20 OFFSET 100000;

Two problems. First, performance: the database still has to walk and discard those 100,000 rows before returning your 20. Offset scans get linearly slower the deeper you page. Second, correctness: if a new row is inserted while a user paginates, every subsequent page shifts by one. Users see duplicates or skip records entirely.

Cursor-based pagination fixes both. Instead of "skip N rows," you say "give me rows after this specific point."

How cursors work

A cursor is an opaque pointer to a position in an ordered result set — usually encoding the sort key of the last item you saw. The query becomes a WHERE clause instead of an OFFSET:

SELECT * FROM events
WHERE created_at < '2026-05-29T10:00:00Z'
ORDER BY created_at DESC
LIMIT 20;

This uses the index on created_at directly. It's fast at any depth because there's no scanning-and-discarding.

The one gotcha: your sort column must be unique and stable, or you'll skip/duplicate rows that share a timestamp. The fix is a composite cursor — sort by (created_at, id) and tie-break on id.

A working implementation

Here's a Node.js endpoint using a composite cursor, with the cursor base64-encoded so clients treat it as opaque:

import express from "express";
const app = express();

function encodeCursor(row) {
  const raw = `${row.created_at.toISOString()}|${row.id}`;
  return Buffer.from(raw).toString("base64url");
}

function decodeCursor(cursor) {
  const raw = Buffer.from(cursor, "base64url").toString("utf8");
  const [createdAt, id] = raw.split("|");
  return { createdAt, id: Number(id) };
}

app.get("/events", async (req, res) => {
  const limit = Math.min(Number(req.query.limit) || 20, 100);
  const cursor = req.query.cursor ? decodeCursor(req.query.cursor) : null;

  // Fetch limit + 1 to detect whether another page exists
  const rows = await db.query(
    `SELECT id, created_at, payload FROM events
     WHERE ($1::timestamptz IS NULL)
        OR (created_at, id) < ($1, $2)
     ORDER BY created_at DESC, id DESC
     LIMIT $3`,
    [cursor?.createdAt ?? null, cursor?.id ?? null, limit + 1]
  );

  const hasMore = rows.length > limit;
  const page = hasMore ? rows.slice(0, limit) : rows;

  res.json({
    data: page,
    next_cursor: hasMore ? encodeCursor(page[page.length - 1]) : null,
  });
});

Two details that matter in production. Fetching limit + 1 rows is a cheap trick to know whether a next_cursor should be returned — no separate COUNT(*) needed. And the row comparison (created_at, id) < ($1, $2) is PostgreSQL row-value syntax, which compares tuples lexicographically and maps cleanly to a composite index.

Consuming it from the client

The client never builds cursors — it just follows them:

async function fetchAllEvents() {
  let cursor = null;
  const all = [];

  do {
    const url = new URL("https://api.example.com/events");
    url.searchParams.set("limit", "100");
    if (cursor) url.searchParams.set("cursor", cursor);

    const res = await fetch(url);
    const { data, next_cursor } = await res.json();
    all.push(...data);
    cursor = next_cursor;
  } while (cursor);

  return all;
}

When offset is still fine

Cursor pagination has a tradeoff: you can't jump to "page 47" because cursors are sequential. If your UI genuinely needs numbered page links over a small, stable dataset, offset is fine. But for infinite scroll, feeds, syncing, and any large or fast-changing table, cursors win on both speed and consistency.

Closing

Getting pagination right is one of those quiet markers of a well-designed API — and it's a lot easier to get right when you can test cursors against real responses before shipping. APIKumo lets you build, document, and exercise endpoints like these directly in a shared workspace, so you can verify your next_cursor behaves across edge cases instead of finding out in production. Design the contract, paginate with confidence.

Idempotency Keys: How to Make Your API Requests Safe to Retry

Mean — Thu, 28 May 2026 02:07:07 +0000

Idempotency Keys: How to Make Your API Requests Safe to Retry

Networks fail. Servers time out. Users double-click submit buttons. When any of these happen with a non-idempotent API request, you end up with duplicate charges, duplicate orders, or corrupted state — the kind of bug that's infuriating to debug at 2am.

Idempotency keys are the standard solution. They're a small addition to your API design that makes retries completely safe. Here's how they work and how to implement them.

What Is an Idempotency Key?

An idempotency key is a unique identifier the client generates and sends with a request. The server uses it to detect duplicate requests and return the same response instead of processing the operation again.

The client sends:

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

{"amount": 4999, "currency": "usd", "customer_id": "cus_123"}

If the network drops and the client retries with the same key, the server returns the original response — no second charge.

Why GET Isn't Enough

GET requests are idempotent by definition (reading doesn't change state). The problem is POST, PUT, and PATCH requests that mutate data. A naive retry of POST /payments without an idempotency key will create two payments. Your users will notice.

Implementing Idempotency Keys on the Server

Here's a minimal Express.js middleware that adds idempotency support to any route:

const crypto = require('crypto');

// In-memory store — use Redis in production
const idempotencyStore = new Map();

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

  // Skip for non-mutating methods
  if (!key || ['GET', 'HEAD', 'OPTIONS'].includes(req.method)) {
    return next();
  }

  if (idempotencyStore.has(key)) {
    const cached = idempotencyStore.get(key);

    // If still processing, return 409 Conflict
    if (cached.status === 'processing') {
      return res.status(409).json({
        error: 'A request with this idempotency key is already in progress'
      });
    }

    // Return the cached response
    return res.status(cached.statusCode).json(cached.body);
  }

  // Mark as processing
  idempotencyStore.set(key, { status: 'processing' });

  // Intercept the response to cache it
  const originalJson = res.json.bind(res);
  res.json = (body) => {
    idempotencyStore.set(key, {
      status: 'complete',
      statusCode: res.statusCode,
      body
    });
    return originalJson(body);
  };

  next();
}

app.use(idempotencyMiddleware);

In production, replace the Map with Redis and set a TTL (24 hours is common):

const redis = require('redis');
const client = redis.createClient();

async function getIdempotencyRecord(key) {
  const data = await client.get(`idempotency:${key}`);
  return data ? JSON.parse(data) : null;
}

async function setIdempotencyRecord(key, record, ttlSeconds = 86400) {
  await client.setEx(
    `idempotency:${key}`,
    ttlSeconds,
    JSON.stringify(record)
  );
}

Generating Keys on the Client

The client is responsible for generating idempotency keys. Use UUIDs — they're long enough to avoid collisions and widely supported:

import uuid
import requests

def create_payment(amount: int, currency: str, customer_id: str) -> dict:
    """
    Creates a payment with automatic retry safety via idempotency key.
    The key is tied to the logical operation, not the HTTP request.
    """
    idempotency_key = str(uuid.uuid4())

    response = requests.post(
        'https://api.example.com/payments',
        json={
            'amount': amount,
            'currency': currency,
            'customer_id': customer_id
        },
        headers={
            'Idempotency-Key': idempotency_key,
            'Authorization': 'Bearer your-token'
        }
    )
    response.raise_for_status()
    return response.json()

Critical rule: generate the key once per logical operation, not per HTTP request. Store it before making the call, so that if your process crashes between attempts you can retry with the same key:

# Persist the key BEFORE the first attempt
operation_id = str(uuid.uuid4())
db.save_pending_payment(order_id, operation_id)

# Now retry safely — same key every time
for attempt in range(1, 4):
    try:
        result = requests.post(
            'https://api.example.com/payments',
            json=payload,
            headers={'Idempotency-Key': operation_id}
        )
        result.raise_for_status()
        break
    except requests.RequestException:
        if attempt == 3:
            raise
        time.sleep(2 ** attempt)  # exponential backoff

What to Return for Duplicate Requests

Always return exactly the same status code and body as the original response — even if the original returned an error. If the first request failed with a 422 validation error, a retry with the same key should return the same 422, not attempt the operation again.

The one exception: if the original request is still in-flight (a race condition), return 409 Conflict to signal that the client should wait before retrying.

Common Mistakes

Scoping keys too broadly. An idempotency key should be scoped to a single resource type and operation. Don't reuse the same key across POST /payments and POST /refunds — treat them as separate operations.

Expiring keys too quickly. If a user comes back to retry an operation three days later, they expect the same outcome. 24 hours is a minimum; 7 days is safer for most payment flows.

Not validating the request body matches. If a client sends the same key but with a different amount, that's likely a bug. Return a 422 and log it — don't silently process a different operation.

Testing Idempotency

Add an explicit test that fires the same request twice and asserts only one side effect occurred:

test('duplicate payment request returns same result without charging twice', async () => {
  const key = 'test-key-' + Date.now();
  const payload = { amount: 1000, currency: 'usd', customer_id: 'cus_test' };

  const first = await api.post('/payments', payload, { 'Idempotency-Key': key });
  const second = await api.post('/payments', payload, { 'Idempotency-Key': key });

  expect(first.body.id).toEqual(second.body.id);  // Same payment ID
  expect(await db.countPayments('cus_test')).toBe(1);  // Only one charge
});

Wrapping Up

Idempotency keys are a small addition that prevent a whole class of serious bugs. Any API that accepts money, creates resources, or triggers irreversible actions should support them — and clients should use them by default.

When you're building and testing APIs that require this kind of reliability, APIKumo makes it easy to set up custom request headers like Idempotency-Key as part of your collection configuration, so every developer on your team sends them consistently without thinking about it.

Idempotency Keys: How to Make Your API Calls Safe to Retry

Mean — Wed, 27 May 2026 02:08:22 +0000

Idempotency Keys: How to Make Your API Calls Safe to Retry

Network failures happen. A request times out, a connection drops, a load balancer restarts mid-flight. The question isn't whether you'll face this — it's what happens when your client retries and the server already processed the first attempt.

For read-only requests (GET, HEAD), this is painless: retry as many times as you like. But for write operations — charging a card, creating an order, sending an email — retrying a request that already succeeded can cause real damage: double charges, duplicate orders, or a customer's inbox flooded with the same confirmation email.

Idempotency keys are the standard solution. They're simple, widely supported, and often misunderstood.

What Is an Idempotency Key?

An idempotency key is a unique string the client sends with a write request. The server uses it to deduplicate: if it sees the same key twice, it returns the cached result from the first successful call instead of executing the operation again.

The client generates the key (usually a UUID), and the server stores it alongside the result for a window of time (commonly 24 hours).

Stripe popularised this pattern with their Idempotency-Key header, and it's now used by Stripe, Braintree, Adyen, Square, and many other payment and infrastructure APIs.

Implementing It Server-Side (Node.js Example)

Here's a minimal Express implementation that stores idempotency keys in Redis:

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

const app = express();
const client = redis.createClient();
app.use(express.json());

app.post('/charges', async (req, res) => {
  const idempotencyKey = req.headers['idempotency-key'];

  if (!idempotencyKey) {
    return res.status(400).json({ error: 'Idempotency-Key header is required' });
  }

  // Check for a cached result
  const cached = await client.get(`idem:${idempotencyKey}`);
  if (cached) {
    return res.status(200).json(JSON.parse(cached));
  }

  // Process the charge
  const result = { id: uuidv4(), amount: req.body.amount, status: 'succeeded' };

  // Cache the result for 24 hours
  await client.setEx(`idem:${idempotencyKey}`, 86400, JSON.stringify(result));

  res.status(201).json(result);
});

Key things to note: the key is validated before processing, and the result is stored after success. If the operation fails, don't cache — the client should be able to retry with the same key after fixing the error.

Sending Idempotency Keys Client-Side (Python)

On the client side, generate a stable key per logical operation — not per HTTP attempt:

import uuid
import httpx
from tenacity import retry, stop_after_attempt, wait_exponential

# Generate ONCE per logical operation, persist if needed
idempotency_key = str(uuid.uuid4())

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
def create_charge(amount_cents: int) -> dict:
    response = httpx.post(
        "https://api.example.com/charges",
        json={"amount": amount_cents, "currency": "usd"},
        headers={"Idempotency-Key": idempotency_key},
        timeout=10.0,
    )
    response.raise_for_status()
    return response.json()

# All three attempts use the same key — only one charge is created
charge = create_charge(2000)

The mistake to avoid: generating a new key on each retry. If the first request succeeded but the response was lost in transit, a new key triggers a second charge.

What to Watch Out For

A few edge cases that bite teams in production:

Conflicting payloads: If a client sends the same key with different request bodies, the server should return a 422 Unprocessable Entity or 409 Conflict — not silently use the first result. Always include a payload hash check.

Key collisions: Use UUID v4, not sequential IDs or timestamps. The chance of a collision over 24 hours is astronomically low with proper UUIDs.

Scope: Keys should be scoped to an endpoint or resource type. A key used for /charges shouldn't be reusable on /refunds.

TTL expiry: After the key expires, a replay of the request is a brand new operation. Make sure your clients understand this window.

Testing This Without a Live Server

When building and testing idempotency logic, it's useful to fire the same request multiple times and inspect the response headers and bodies side-by-side. APIKumo makes this straightforward — you can save the request with the idempotency key set as a header variable, run it back-to-back, and compare responses in the history view to confirm the server is deduplicating correctly. No scripting required.

Idempotency keys are one of those patterns that seem optional until something goes wrong at 2am. Bake them in from day one.

Idempotency Keys: The API Pattern That Saves You From Duplicate Payments and Phantom Records

Mean — Tue, 26 May 2026 02:07:37 +0000

Idempotency Keys: The API Pattern That Saves You From Duplicate Payments and Phantom Records

Your user clicks "Pay" and nothing happens. So they click again. Your server processes both requests — and charges the card twice.

This is one of the most damaging bugs you can ship, and it's entirely preventable. The solution has been hiding in plain sight in Stripe's API since 2013: idempotency keys.

What Is an Idempotency Key?

An idempotency key is a unique token the client sends with a mutating request (POST, PATCH, DELETE). The server uses it to guarantee that no matter how many times you send the same request — due to retries, network failures, or impatient button-clicks — the operation only executes once.

The word comes from mathematics: a function f is idempotent if f(f(x)) = f(x). Applying it twice is the same as applying it once.

Stripe implements it like this:

POST /v1/charges
Authorization: Bearer sk_live_...
Idempotency-Key: charge_user_42_order_891
Content-Type: application/json

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

If the client sends this request again with the same Idempotency-Key, Stripe returns the cached response from the first execution — no second charge.

Implementing Idempotency Keys in Your Own API

Here's a minimal implementation in Node.js with Express and Redis:

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

const app = express();
const cache = redis.createClient();
const IDEMPOTENCY_TTL = 86400; // 24 hours in seconds

app.use(express.json());

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

  // Only applies to mutating methods
  if (!['POST', 'PATCH', 'DELETE'].includes(req.method) || !key) {
    return next();
  }

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

  if (cached) {
    const { statusCode, body } = JSON.parse(cached);
    return res.status(statusCode).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(
        cacheKey,
        IDEMPOTENCY_TTL,
        JSON.stringify({ statusCode: res.statusCode, body })
      );
    }
    return originalJson(body);
  };

  next();
}

app.use(idempotencyMiddleware);

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

Key design decisions baked in:

Only mutating methods get the idempotency treatment. GET requests are already safe to retry.
500 errors are never cached. A server crash shouldn't lock the client into a permanent error.
24-hour TTL. Long enough to cover any reasonable retry window, short enough to not bloat your cache forever.

Generating Idempotency Keys on the Client

The key should be unique per logical operation, not per HTTP request. Here's a pattern that works:

import uuid
import hashlib

def make_idempotency_key(user_id: str, operation: str, resource_id: str) -> str:
    """
    Deterministic key: same inputs always produce the same key.
    Safe to call multiple times before sending.
    """
    raw = f"{user_id}:{operation}:{resource_id}"
    return hashlib.sha256(raw.encode()).hexdigest()[:32]

# Example usage
key = make_idempotency_key(
    user_id="user_42",
    operation="charge",
    resource_id="order_891"
)
# → always produces the same key for this user + order combination

import httpx

response = httpx.post(
    "https://api.example.com/charges",
    headers={"Idempotency-Key": key},
    json={"amount": 2000, "currency": "usd"}
)

Using a deterministic hash instead of a random UUID means the client can reconstruct the key after a crash, without needing to store it separately.

What About Conflicts?

What if the same idempotency key arrives with a different request body? This indicates a client bug — not a legitimate retry. Return a 422 Unprocessable Entity:

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

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

  if (cached) {
    const stored = JSON.parse(cached);
    const bodyHash = hashBody(req.body);

    if (stored.bodyHash !== bodyHash) {
      return res.status(422).json({
        error: 'idempotency_key_reuse',
        message: 'This idempotency key was used with a different request body.'
      });
    }

    return res.status(stored.statusCode).json(stored.body);
  }

  // Store body hash alongside the response
  req.idempotencyBodyHash = hashBody(req.body);
  next();
}

function hashBody(body) {
  return require('crypto')
    .createHash('sha256')
    .update(JSON.stringify(body))
    .digest('hex');
}

The Header Name Convention

There's no RFC standard here yet, but the de facto conventions are:

Header	Used by
`Idempotency-Key`	Stripe, Adyen, many fintech APIs
`X-Idempotency-Key`	Some older APIs
`X-Request-ID`	Often used for tracing, sometimes idempotency

Stick with Idempotency-Key for new APIs — it's become the community standard.

Testing Idempotency in Your API Client

Before shipping idempotency support, you want to verify that duplicate requests actually return the same cached response. This is where having a good API testing environment matters enormously. With APIKumo, you can create a collection with pre-request scripts that automatically generate and re-use idempotency keys across retried requests — making it straightforward to simulate retry scenarios and confirm your server behaves correctly, without writing a separate test harness.

Wrapping Up

Idempotency keys are a small header with enormous consequences. They're the difference between a payment API users trust and one that occasionally charges customers twice. The implementation is under 50 lines of middleware, the client-side change is a single header, and the protection they provide is permanent.

If you're building any API that processes money, creates records, or sends messages — idempotency keys should be non-negotiable.

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

Mean — Mon, 25 May 2026 02:06:20 +0000

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.

Idempotency Keys: The One API Pattern That Prevents Duplicate Charges and Phantom Orders

Mean — Sun, 24 May 2026 02:06:35 +0000

Idempotency Keys: The One API Pattern That Prevents Duplicate Charges and Phantom Orders

Your user clicks "Place Order." The request hits your server, the charge succeeds, and then — network timeout. The client never got the 200. So it retries. Now you have two charges and one very angry customer.

This is exactly the problem idempotency keys were invented to solve. If you're building any API that mutates state — payments, order creation, email sends — not implementing idempotency isn't just a bug risk, it's a liability.

What Is an Idempotency Key?

An idempotency key is a unique identifier the client generates and includes with every mutating request. The server uses it to detect duplicate submissions and return the same result as the original, without re-executing the operation.

The Stripe API made this pattern mainstream. Pass Idempotency-Key: <uuid> in the header, and Stripe guarantees that retrying the same request never creates a second charge.

Implementing Idempotency on the Server

Here's a minimal but production-ready implementation in Python (FastAPI + Redis):

import hashlib
import json
import redis
from fastapi import FastAPI, Header, HTTPException, Request
from typing import Optional

app = FastAPI()
r = redis.Redis(host="localhost", port=6379, decode_responses=True)

IDEMPOTENCY_TTL = 86400  # 24 hours

@app.post("/orders")
async def create_order(
    request: Request,
    idempotency_key: Optional[str] = Header(None, alias="Idempotency-Key")
):
    body = await request.json()

    if idempotency_key:
        cache_key = f"idempotency:{idempotency_key}"
        cached = r.get(cache_key)

        if cached:
            # Return the original response — no duplicate processing
            return json.loads(cached)

    # Process the order for real
    order = process_order(body)
    result = {"order_id": order.id, "status": "created"}

    if idempotency_key:
        # Cache the result for future retries
        r.setex(cache_key, IDEMPOTENCY_TTL, json.dumps(result))

    return result

Key implementation decisions here:

TTL of 24 hours: Long enough to cover any reasonable retry window.
Cache after success only: If the request failed before producing a result, don't cache — let the retry actually run.
Scope keys per endpoint: A key for /orders shouldn't collide with one for /refunds. Prefix with the route or resource type.

The Client Side: Generating and Reusing Keys

The client must generate the key before sending and reuse it on every retry of the same logical operation:

import { v4 as uuidv4 } from 'uuid';

async function placeOrder(cartId, paymentToken) {
  // Generate ONCE per logical operation — store it if you need to retry
  const idempotencyKey = uuidv4();

  const response = await fetchWithRetry('https://api.example.com/orders', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey,
    },
    body: JSON.stringify({ cartId, paymentToken }),
  });

  return response.json();
}

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const res = await fetch(url, options);
      if (res.ok || res.status < 500) return res; // Don't retry 4xx
      await sleep(Math.pow(2, attempt) * 200); // Exponential backoff
    } catch (e) {
      if (attempt === maxRetries - 1) throw e;
    }
  }
}

Notice that the same idempotencyKey is passed on every retry call — the key must not be regenerated between attempts or you defeat the purpose entirely.

Edge Cases You Must Handle

1. Mismatched request bodies. If a client sends the same key with a different body, that's likely a client bug. Return 422 Unprocessable Entity with a clear error rather than silently returning the cached response.

2. In-flight requests. If a second request arrives with the same key while the first is still processing, return 409 Conflict with a Retry-After header. Don't start a second execution.

3. Partial failures. If your order creation writes to a database but then fails to charge the card, did you cache a result? No — only cache after the entire operation succeeds.

4. Key exhaustion / replay attacks. Keys should be UUIDs (122 bits of entropy). Don't let clients reuse keys for genuinely new operations.

When You Don't Need Idempotency Keys

GET, HEAD, and OPTIONS are already idempotent by definition — calling them twice has no side effects. You only need explicit keys for POST (and sometimes PATCH) when the operation isn't naturally idempotent.

PUT is usually safe without keys because it's designed to be idempotent: PUT /orders/123 with the same body should produce the same result every time.

Testing Idempotency in Your API Client

Before shipping, you should test three scenarios:

Send the same key twice — verify identical responses and a single DB record.
Send the same key with a different body — verify rejection.
Send concurrent requests with the same key — verify exactly one succeeds.

This is the kind of testing that's easy to forget in the rush to ship but painful to debug in production.

If you want to explore and test idempotency behaviour across your API collection — inspecting request headers, replaying calls, and comparing responses — APIKumo makes it easy to build and share those test scenarios directly alongside your API documentation.

Idempotency Keys: The API Safety Net You Probably Aren't Using

Mean — Sat, 23 May 2026 02:13:10 +0000

Idempotency Keys: The API Safety Net You Probably Aren't Using

Network failures happen at the worst possible times. A user clicks "Pay Now," your request hits the payment API, the connection drops before the response arrives — and now you don't know if the charge went through. Do you retry and risk a double charge? Do you let it fail and frustrate the user?

Idempotency keys solve this problem cleanly. They're one of those API patterns that seems like a small detail until the moment you desperately need it, and then they feel like magic.

What Is an Idempotency Key?

An idempotency key is a unique value you generate on the client side and attach to a request. The server uses it to de-duplicate: if it sees the same key twice, it returns the cached result of the first request rather than executing the operation again.

The practical effect is that retrying a failed request is always safe. The operation runs once — exactly once — no matter how many times you send it.

The Classic Problem Without Idempotency

import requests

def charge_customer(customer_id: str, amount_cents: int) -> dict:
    response = requests.post(
        "https://api.payments.example/charges",
        json={"customer_id": customer_id, "amount": amount_cents},
        headers={"Authorization": "Bearer sk_live_..."}
    )
    response.raise_for_status()
    return response.json()

# If this times out after the server processed it, calling it again = double charge
charge_customer("cus_abc123", 4999)

If raise_for_status() throws a ConnectionError or a timeout, you have no idea whether the charge happened. You're stuck.

Adding Idempotency Keys

Most APIs that care about this (Stripe, Brex, Adyen) accept idempotency keys via a header:

import uuid
import requests
from typing import Optional

def charge_customer_safely(
    customer_id: str,
    amount_cents: int,
    idempotency_key: Optional[str] = None
) -> dict:
    # Generate a stable key for this specific operation
    key = idempotency_key or str(uuid.uuid4())

    response = requests.post(
        "https://api.payments.example/charges",
        json={"customer_id": customer_id, "amount": amount_cents},
        headers={
            "Authorization": "Bearer sk_live_...",
            "Idempotency-Key": key,
        }
    )
    response.raise_for_status()
    return response.json()

Now you can retry freely:

import time

key = str(uuid.uuid4())  # Generate ONCE, reuse on retries
max_retries = 3

for attempt in range(max_retries):
    try:
        result = charge_customer_safely("cus_abc123", 4999, idempotency_key=key)
        print(f"Charged successfully: {result['id']}")
        break
    except requests.exceptions.Timeout:
        if attempt == max_retries - 1:
            raise
        time.sleep(2 ** attempt)  # Exponential backoff

The key insight: the key is generated before the first attempt, not per-attempt. Reusing the same key across retries is what makes this safe.

Implementing Idempotency on Your Own API

If you're building an API, adding idempotency support is worth the effort. Here's a minimal implementation in Node.js with Express and Redis:

const express = require('express');
const redis = require('redis');

const app = express();
const client = redis.createClient();
app.use(express.json());

async function idempotencyMiddleware(req, res, next) {
  const key = req.headers['idempotency-key'];
  if (!key) return next(); // Key is optional — skip if absent

  const cached = await client.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) => {
    await client.setEx(
      `idem:${key}`,
      86400, // Cache for 24 hours
      JSON.stringify({ status: res.statusCode, body })
    );
    return originalJson(body);
  };

  next();
}

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

A few rules to enforce:

Scope keys to the authenticated user. User A's key should never collide with User B's.
Return 422 if the same key is reused with different request bodies. Mismatched payloads suggest a bug in the client.
Set a reasonable TTL. 24 hours is standard; some APIs go up to 7 days.

What Makes a Good Idempotency Key?

Keys should be:

Unique per logical operation — not per HTTP request
Cryptographically random — UUID v4 is the standard choice
Stable under retries — generate once, persist it until the operation succeeds

A common mistake is generating a new UUID on every retry. That completely defeats the purpose.

// ❌ Wrong — new key per attempt
for (let i = 0; i < 3; i++) {
  await fetch('/charges', {
    headers: { 'Idempotency-Key': crypto.randomUUID() } // New key each time!
  });
}

// ✅ Correct — stable key across all retries
const key = crypto.randomUUID(); // Generated once
for (let i = 0; i < 3; i++) {
  await fetch('/charges', {
    headers: { 'Idempotency-Key': key } // Reused across retries
  });
}

Which Endpoints Need Idempotency?

Not all operations need this treatment. A good rule of thumb:

Yes: POST /charges, POST /orders, POST /transfers — anything that moves money or creates unique records
Yes: Any webhook delivery retry mechanism
No: GET and DELETE — these are already naturally idempotent
Judgment call: PUT — it's idempotent by definition in REST, but explicit keys don't hurt for extra safety

Testing Idempotent Endpoints

Verify your implementation handles three cases:

KEY="test-key-$(date +%s)"

# First request — should process normally
curl -X POST https://api.example.com/charges \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4999}' \
  | jq '.id'  # Note the returned ID

# Second request with same key — should return identical response
curl -X POST https://api.example.com/charges \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 4999}' \
  | jq '.id'  # Should be the same ID

# Same key, different body — should return 422
curl -X POST https://api.example.com/charges \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 9999}' \
  | jq '.error'

If your API passes all three, your idempotency implementation is solid.

Idempotency keys are one of those features that's invisible when it works and catastrophic when it's missing. If you're working with payment flows, order creation, or any operation your users would be upset to see run twice, add idempotency support now — before the production incident.

If you want to test how your idempotent endpoints behave end-to-end, APIKumo makes it straightforward to craft requests with custom headers, save idempotency keys as environment variables, and replay the same request multiple times to verify your de-duplication logic holds up. It's the kind of sanity check that's easy to skip and painful to skip.

Idempotency Keys: The Simple Trick That Prevents Duplicate Payments and Ghost Orders

Mean — Fri, 22 May 2026 02:07:39 +0000

Idempotency Keys: The Simple Trick That Prevents Duplicate Payments and Ghost Orders

You've seen it happen. A user clicks "Place Order," the network hiccups, the request times out, and now they've been charged twice. Or the charge went through but the order never appeared. Neither outcome is acceptable, and both are preventable — with idempotency keys.

What Is an Idempotency Key?

An idempotency key is a unique identifier you attach to a request so that the server can safely process it exactly once, no matter how many times the client retries. If the server receives the same key again, it returns the original response instead of executing the operation a second time.

The concept is borrowed from mathematics: an operation is idempotent if applying it multiple times produces the same result as applying it once. DELETE /users/42 is naturally idempotent — deleting an already-deleted user changes nothing. POST /orders is not — sending it twice creates two orders.

Idempotency keys make non-idempotent operations safe to retry.

How It Works in Practice

The client generates a unique key (typically a UUID v4) before sending the request. It attaches the key as a header, usually Idempotency-Key. The server stores the key and the response in a short-lived cache (24 hours is common). On retry, the server finds the key, skips execution, and returns the stored response.

Here's a payment request using this pattern in Python:

import uuid
import httpx

def charge_customer(customer_id: str, amount_cents: int) -> dict:
    idempotency_key = str(uuid.uuid4())  # generate once, store for retries

    headers = {
        "Authorization": "Bearer sk_live_...",
        "Idempotency-Key": idempotency_key,
        "Content-Type": "application/json",
    }

    payload = {
        "customer": customer_id,
        "amount": amount_cents,
        "currency": "usd",
    }

    for attempt in range(3):
        try:
            response = httpx.post(
                "https://api.stripe.com/v1/charges",
                headers=headers,   # same key on every retry
                json=payload,
                timeout=10,
            )
            response.raise_for_status()
            return response.json()
        except (httpx.TimeoutException, httpx.ConnectError):
            if attempt == 2:
                raise
            continue

The critical detail: the idempotency_key is generated once before the loop, not inside it. Every retry sends the identical key, so the server knows they're all the same request.

Implementing the Server Side

If you're building an API that accepts payments, bookings, or any state-changing operation, you need to store and check idempotency keys yourself.

import { randomUUID } from "crypto";
import { redis } from "./redis";

async function handleCharge(req: Request): Promise<Response> {
  const key = req.headers.get("Idempotency-Key");

  if (!key) {
    return Response.json({ error: "Idempotency-Key header required" }, { status: 400 });
  }

  // Check for a cached response
  const cached = await redis.get(`idem:${key}`);
  if (cached) {
    return Response.json(JSON.parse(cached), { status: 200 });
  }

  // Execute the operation
  const result = await processCharge(req);

  // Store result for 24 hours
  await redis.set(`idem:${key}`, JSON.stringify(result), "EX", 86400);

  return Response.json(result, { status: 201 });
}

A few implementation notes worth keeping in mind:

Scope keys to the user. Store the key as user:{userId}:idem:{key} to prevent one user from accidentally (or maliciously) colliding with another's key.

Don't cache errors. If the operation fails with a 500, don't store the result — let the client retry with the same key and give the operation another chance. Do cache 4xx errors, since a bad request won't succeed on retry.

Return the same status code. If the original response was 201 Created, the cached response should also be 201, not 200. Clients sometimes branch on status codes.

When to Require Idempotency Keys

Not every endpoint needs them. GET requests are already safe to repeat. Natural idempotent operations (DELETE, PUT with full resource replacement) don't need extra help. But you should require idempotency keys for:

Payment and refund creation
Order placement
Email or SMS sends
Any operation that creates a resource or triggers a side effect

Stripe, Braintree, and Adyen all require idempotency keys on charge endpoints for exactly this reason. If you're building a public API, following their lead protects your users and your data integrity.

Testing Idempotency

Before shipping, verify the behaviour explicitly in your test suite:

def test_duplicate_charge_is_ignored():
    key = str(uuid.uuid4())
    first  = client.post("/charges", headers={"Idempotency-Key": key}, json=payload)
    second = client.post("/charges", headers={"Idempotency-Key": key}, json=payload)

    assert first.status_code == 201
    assert second.status_code == 201
    assert first.json()["id"] == second.json()["id"]  # same charge, not a new one
    assert db.count_charges() == 1                    # only one record created

Idempotency keys are one of those small API design choices with an outsized reliability impact. They're cheap to implement and expensive to skip — your support team (and your users) will thank you.

If you want to test idempotency key behaviour against your API without writing scaffolding from scratch, APIKumo lets you set custom headers like Idempotency-Key per-request or as collection-level defaults, so you can replay the same request with identical headers and verify your server handles duplicates correctly. It's a quick sanity check before you ship.

Idempotency Keys: The Simple Pattern That Prevents Duplicate API Requests

Mean — Thu, 21 May 2026 02:14:41 +0000

Idempotency Keys: The Simple Pattern That Prevents Duplicate API Requests

If you've ever hit "Submit" on a payment form twice and got charged twice, you've experienced what happens when an API lacks idempotency. It's one of the most underappreciated patterns in API design — and one of the most important for anything involving money, email sends, order creation, or any operation that should happen exactly once.

What Is Idempotency?

An operation is idempotent if performing it multiple times produces the same result as performing it once. GET requests are naturally idempotent — fetching a resource ten times doesn't change anything. But POST requests that create resources are not — posting the same order twice will create two orders.

Idempotency keys solve this. The client generates a unique key per logical operation and sends it with each request. The server uses that key to detect duplicates and return the original result instead of processing the request again.

POST /payments
Idempotency-Key: a7f3d9c2-1b4e-4f6a-8e2d-9c3f1a5b7e8d
Content-Type: application/json

{
  "amount": 9900,
  "currency": "usd",
  "customer_id": "cus_abc123"
}

If the network drops after the server processes this request but before the client receives the response, the client can safely retry with the same Idempotency-Key. The server recognizes the key, finds the stored result, and returns it without charging the customer again.

Implementing Idempotency on the Server

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

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

const app = express();
const client = redis.createClient();
const TTL_SECONDS = 86400; // 24 hours

app.use(express.json());

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

  if (!key) return next(); // idempotency is optional for this endpoint

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

  next();
}

app.post('/payments', idempotencyMiddleware, async (req, res) => {
  // Your actual payment logic here
  const payment = await processPayment(req.body);
  res.status(201).json(payment);
});

A few important details:

Scope the key to the endpoint — the same key value used on /payments and /orders should be treated as separate keys.
Set a TTL — 24 hours is a common default; Stripe uses 24 hours, others use up to 48.
Return the original status code — if the original request returned a 422 validation error, return that same 422 on retries, not a 200.

Generating Keys on the Client

Clients should generate a new UUID per logical request, persisting it locally until they receive a definitive success or failure:

import uuid
import httpx

def create_payment(amount: int, currency: str, customer_id: str) -> dict:
    idempotency_key = str(uuid.uuid4())  # generate once, reuse on retry

    for attempt in range(3):
        try:
            response = httpx.post(
                "https://api.example.com/payments",
                headers={"Idempotency-Key": idempotency_key},
                json={
                    "amount": amount,
                    "currency": currency,
                    "customer_id": customer_id,
                },
                timeout=10.0,
            )

            if response.status_code in (200, 201):
                return response.json()

            if response.status_code in (400, 422):
                raise ValueError(f"Bad request: {response.text}")

            # 5xx or network error — retry with the SAME key
        except httpx.TimeoutException:
            if attempt == 2:
                raise

    raise RuntimeError("Payment failed after 3 attempts")

The key insight: generate the UUID before the first attempt and keep using it on retries. If you generate a new UUID on each retry, you've defeated the entire purpose.

Handling Conflicts

What if the same idempotency key is used with different request bodies? This is almost certainly a client bug. The server should return a 409 Conflict with a clear error message:

{
  "error": "idempotency_conflict",
  "message": "This idempotency key was already used with different request parameters."
}

What About Database Transactions?

If your datastore supports it, you can implement idempotency without a separate cache by using a unique constraint on an idempotency_key column:

CREATE TABLE payments (
  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  idempotency_key VARCHAR(255) UNIQUE,
  amount      INTEGER NOT NULL,
  customer_id VARCHAR(255) NOT NULL,
  created_at  TIMESTAMPTZ DEFAULT now()
);

On conflict, return the existing row. This is simpler and stays consistent with your primary database.

Closing Thoughts

Idempotency keys are a small implementation effort with a huge reliability payoff. Any API endpoint that creates or mutates a resource — payments, orders, email sends, user signups — should support them. Your users' retry logic (and their patience) will thank you.

When you're exploring and testing APIs that use idempotency keys, APIKumo makes it easy to set and manage custom headers like Idempotency-Key across your requests, so you can verify that your server handles retries correctly without writing throw-away test scripts.