DEV Community: APIKumo

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.

Webhook Verification: How to Validate Every Incoming Request (and Why You Must)

Mean — Wed, 20 May 2026 02:07:12 +0000

Webhook Verification: How to Validate Every Incoming Request (and Why You Must)

Webhooks are the backbone of event-driven integrations — Stripe charges, GitHub pushes, Slack commands, Shopify orders. They're simple on the surface: a third-party service sends an HTTP POST to your endpoint when something happens.

The problem? Anyone on the internet can POST to your webhook endpoint. Without verification, a malicious actor can send fake events and trick your system into shipping an order, granting permissions, or triggering a refund. Webhook signature verification is non-negotiable — yet it's often the last thing developers add (if they add it at all).

Here's how to do it right, with real examples.

How Webhook Signatures Work

Most services that send webhooks sign their payloads using HMAC-SHA256. The flow is:

You register your endpoint URL with the service.
The service gives you a secret key (or you generate one).
When the service sends a webhook, it computes HMAC-SHA256(secret, raw_body) and includes the result in a request header (e.g. X-Hub-Signature-256, Stripe-Signature, X-Shopify-Hmac-SHA256).
Your server recomputes the same HMAC and compares it to the header. If they match, the request is authentic.

The critical rule: always compute the HMAC against the raw request body — before any JSON parsing. Parsing and re-serializing can change whitespace and key order, breaking the signature check.

Verifying a Stripe Webhook (Node.js)

Stripe adds a timestamp and a signature to the Stripe-Signature header to protect against replay attacks.

import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET;
const app = express();

// IMPORTANT: use raw body parser for webhook routes
app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];

  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);
  } catch (err) {
    console.error(`Signature verification failed: ${err.message}`);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the verified event
  switch (event.type) {
    case 'payment_intent.succeeded':
      console.log('Payment succeeded:', event.data.object.id);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  res.json({ received: true });
});

Stripe's SDK handles replay-attack protection by rejecting events with a timestamp older than 5 minutes by default.

Verifying a GitHub Webhook (Python)

GitHub uses the X-Hub-Signature-256 header with HMAC-SHA256.

import hashlib
import hmac
import os
from flask import Flask, request, abort

app = Flask(__name__)
GITHUB_SECRET = os.environ['GITHUB_WEBHOOK_SECRET'].encode()

def verify_github_signature(payload_body: bytes, signature_header: str) -> bool:
    if not signature_header or not signature_header.startswith('sha256='):
        return False
    expected = 'sha256=' + hmac.new(
        GITHUB_SECRET, payload_body, hashlib.sha256
    ).hexdigest()
    # Use compare_digest to prevent timing attacks
    return hmac.compare_digest(expected, signature_header)

@app.route('/webhooks/github', methods=['POST'])
def github_webhook():
    signature = request.headers.get('X-Hub-Signature-256', '')
    if not verify_github_signature(request.data, signature):
        abort(400, 'Invalid signature')

    payload = request.get_json()
    event = request.headers.get('X-GitHub-Event')
    print(f'Received {event} event for {payload.get("repository", {}).get("full_name")}')
    return '', 204

Note the use of hmac.compare_digest — this is essential to prevent timing attacks, where an attacker could infer the correct signature by measuring how long comparisons take.

A Generic HMAC Verifier

If you're working with a service that doesn't have an official SDK, here's a reusable helper:

import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhookSignature(
  rawBody: Buffer,
  receivedSig: string,
  secret: string,
  algorithm: 'sha256' | 'sha1' = 'sha256'
): boolean {
  const expectedSig = createHmac(algorithm, secret)
    .update(rawBody)
    .digest('hex');

  const a = Buffer.from(receivedSig.replace(/^sha\d+=/, ''), 'hex');
  const b = Buffer.from(expectedSig, 'hex');

  if (a.length !== b.length) return false;
  return timingSafeEqual(a, b);
}

Common Mistakes to Avoid

1. Parsing the body before verifying. JSON parsers can normalize whitespace or reorder keys. Always verify against the raw bytes.

2. Using === for signature comparison. This leaks timing information. Always use timingSafeEqual / hmac.compare_digest or equivalent.

3. No replay protection. If your service doesn't handle this automatically (like Stripe does), store and check event IDs or validate timestamps.

4. Hardcoding secrets. Store webhook secrets in environment variables or a secrets manager, never in source code.

Testing Webhook Verification Locally

Webhook verification is notoriously hard to test because you need a public URL. Tools like ngrok or smee.io can tunnel traffic to your local machine during development.

This is where having a proper API client environment pays off. APIKumo lets you replay saved webhook payloads against your local endpoint — including the original headers and signatures — so you can iterate on your verification logic without needing to trigger real events from the third-party service every time.

Webhook verification is one of those things that takes 20 minutes to add and can save you from a catastrophic security incident. Add it at day one, not after your first production incident.

Idempotency Keys: The Safety Net Every Mutation API Needs

Mean — Tue, 19 May 2026 02:02:44 +0000

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:

Store the key alongside the result after the operation completes
Check for the key before processing any new request
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:

First request — processes normally, stores result, returns 201
Duplicate request — returns cached result, returns 200, no second charge
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.