Idempotency Patterns

A request is idempotent if making it twice produces the same effect as making it once. For unreliable networks (which is to say, all networks), idempotency is essential — clients retry; without idempotency, retries cause duplicate side effects.

This page is about how to design idempotent APIs and the patterns that work in production.

What idempotent means

Formally: f(f(x)) = f(x). Operationally: the second call has no additional effect.

Examples:

PUT /resource/123 with full state — idempotent (same final state)
DELETE /resource/123 — idempotent (deleted is deleted)
POST /orders creating a new order — NOT idempotent without explicit support
Adding $10 to a balance — NOT idempotent; doubles on retry

POST is the typically-troublesome verb. Most state-creating operations are POST; without idempotency keys, retries duplicate.

Idempotency keys

The standard pattern: clients send a key with the request. Server records the key + response. On retry with the same key, server returns the same response without reprocessing.

POST /api/orders
Idempotency-Key: 8d4f...

{ "amount": 100.00 }

If the request is retried with the same key, the server:

Checks if the key exists
If yes, returns the original response (no reprocessing)
If no, processes the request and stores the key + response

Generating keys

Keys must be unique per logical operation:

UUIDs for general use
Business-meaningful keys when the natural identifier is stable: order-{customer}-{timestamp}
Hash of request payload for cases where the same content shouldn't process twice

Clients generate the key; the server doesn't know what the client considers the same operation.

Server-side storage

Storage requirements:

Persistent (survives server restarts)
Distributed (any server in a cluster sees the same key)
TTL (keys eventually expire)

Common stores: Redis (with TTL), database table with cleanup job, dedicated idempotency service.

Schema:

CREATE TABLE idempotency (
    key VARCHAR(255) PRIMARY KEY,
    request_hash VARCHAR(64),  -- to detect different request with same key
    response_status INT,
    response_body JSONB,
    created_at TIMESTAMP,
    expires_at TIMESTAMP
);

The request_hash lets you detect "key reuse with different payload" — a client error worth flagging.

Concurrent retries

What if two retries hit two different servers simultaneously? Both see "key not found" and both start processing.

Solutions:

Database-level uniqueness

Insert the key with the request before processing. If insert fails (key exists), wait or read the existing record.

-- Atomic check-and-set
INSERT INTO idempotency (key, status) VALUES (?, 'processing')
ON CONFLICT DO NOTHING;

Distributed lock

Acquire a lock on the key before processing. Release after recording response. Other concurrent retries wait or fail.

Optimistic with deduplication

Process both; deduplicate at storage time (transaction with constraint). Wasteful but simple.

TTL

Keys expire eventually. Common: 24 hours.

Too short: legitimate retries (network delay, client retry policy) miss the window. Too long: storage grows; old keys clutter the system.

24 hours covers most retry scenarios. Document the TTL so clients know how long they can safely retry.

What about non-POST verbs?

GET: naturally idempotent (no state change)
PUT: naturally idempotent if the body is the full new state
DELETE: naturally idempotent

POST is the verb that needs idempotency keys. PATCH is between — partial updates can be non-idempotent if the patch references current state.

Specific patterns

Stripe-style

Stripe popularized idempotency keys for payment APIs. Their pattern:

Header: Idempotency-Key: <client-provided>
Different request body with same key → error (client bug detection)
TTL: 24 hours
Documented; client SDKs generate keys automatically

Most payment and financial APIs follow this pattern.

Database upsert

The simplest case: the database itself enforces idempotency via unique constraint:

INSERT INTO orders (id, ...) VALUES (?, ...)
ON CONFLICT (id) DO NOTHING
RETURNING id;

The client provides the ID; duplicates are no-ops. Simpler than full idempotency-key storage; only works when the client generates IDs.

Idempotent operations by design

Some operations are naturally idempotent:

POST /orders/{id}/mark-shipped

Calling it twice has the same effect as once: status = shipped. No need for idempotency keys.

Designing operations to be idempotent by construction is often easier than retrofitting keys.

Common failure patterns

No idempotency support. Network retries duplicate orders.
Idempotency that doesn't survive server restart. In-memory cache; lost on deploy.
Different request body, same key. Should be an error; sometimes silently ignored.
Forgetting cleanup. Idempotency table grows indefinitely.
Idempotency at the wrong granularity. Per-batch when per-item is needed, or vice versa.
Race on concurrent retries. Both pass the "key exists" check; both process.