Server-side state machine: four states of an idempotency key

The four states

By the end of this lesson you will be able to trace any idempotency-key lookup to its correct outcome — and know exactly which HTTP status to expect and why.

When a request with Idempotency-Key arrives, the server looks up the key in a deduplification cache (a Postgres table or Redis entry). There are exactly four outcomes:

1. New — no row exists for this key. The server inserts (key, fingerprint, status=in_progress, expires_at) in the same transaction as the business logic, processes the work, then updates the row with (response_body, response_status, status=completed).

2. In-flight — a row exists with status=in_progress. Another request is already processing this key concurrently. The server returns 409 Conflict with {"error": "idempotency key in use"} immediately. The client backs off and retries.

3. Replay — a row exists with status=completed and a stored response. The server returns the cached response body and status code without re-running any business logic. The client gets one confirmation. The customer is charged once.

4. Mismatch — a row exists for this key, but the fingerprint of the incoming request does not match. The client has reused the key with a different intent (different amount, different recipient). The server returns 422 Unprocessable Entity. The client must generate a fresh key for the new operation.

Why the request fingerprint matters

When you see a 422 on a payment retry, your first instinct should be to check whether the key was reused across different request bodies — not whether the server is broken.

The fingerprint is a hash of the request body (and optionally method, path, and key headers). Stripe hashes the body; payment APIs that route by Stripe-Account include that header too.

Without the fingerprint, a client that accidentally reuses a key for a different amount would silently get back the original response — and the new amount would be lost forever. The fingerprint makes this a hard error (422) instead of silent data loss.

Cost: one SHA-256 per request — microseconds. Cheap insurance.

Where to store the cache

Postgres table (simple, durable):

CREATE TABLE idempotency_keys (
  key          TEXT PRIMARY KEY,
  fingerprint  TEXT NOT NULL,
  response_body JSONB,
  response_status INT,
  status       TEXT NOT NULL DEFAULT 'in_progress',
  expires_at   TIMESTAMPTZ NOT NULL
);
CREATE INDEX ON idempotency_keys (expires_at);

A daily cleanup job deletes rows past expires_at. Stripe v1 held keys for 24 hours; v2 extended to 30 days.

Redis with TTL (higher throughput): SETNX key value EX ttl_seconds — atomic set-if-not-exists. Redis is faster but risks losing entries on async-fsync crash. Payment APIs that hold legal liability keep the authoritative record in Postgres and use Redis as a hot-path read-through cache.