API reliability

Prevents duplicate side effects when clients retry non-idempotent operations due to network failures or timeouts.

Payment processing: client retries a charge after a timeout, risking double-charging the customer; Distributed systems: message broker redelivers a command after a consumer crash; REST APIs: POST endpoint creates a resource and the client cannot tell if the first attempt succeeded

REST APIs, payment gateways (Stripe, PayPal), message queues (Kafka, RabbitMQ), webhook handlers, SaaS platforms

client generates unique key → attaches to mutating request → server stores key+result → retries with same key return cached result

• HTTP headers (Idempotency-Key)
• UUID generation
• request deduplication
• retry middleware
• Stripe API
• webhook delivery

• Natural primary keys (e.g.
• order_id) — only works when the operation has a natural unique identifier
• Optimistic locking with version numbers — handles concurrent updates but not network retries
• Database unique constraints — catches duplicates but surfaces as errors rather than returning the original result

Storing idempotency keys forever — causes unbounded storage growth; use TTL or scope to a time window; Using the same key for different request bodies — server must reject mismatched bodies or risk returning wrong cached result; Generating keys from non-unique data (e.g., timestamp only) — collisions cause one request to silently return another's result; Forgetting to scope keys per-user or per-tenant — key collisions across users can leak results or block legitimate requests; Not handling the in-flight case — two concurrent requests with the same key can both proceed before either stores a result

Idempotent HTTP methods (PUT, DELETE) — built into the protocol vs. client-supplied key for POST; Distributed locks — prevent concurrent execution vs. idempotency keys prevent duplicate execution; Exactly-once delivery — messaging-level guarantee vs. application-level dedup via keys

Coming from SQL databases: may assume the database transaction guarantees no duplicates — network retries happen before the transaction commits, so the server never sees the first attempt; Coming from JavaScript/fetch: may assume the browser handles retries automatically — fetch does not retry; clients must implement retry logic explicitly

• Idempotent operations
• exactly-once delivery
• request deduplication
• retry strategies
• distributed transactions

Do not use for read-only (GET) requests or operations that are already naturally idempotent (PUT replacing by ID). Storage cost grows with key retention window, so production systems typically expire keys after 24 hours. Boundary condition: if the server crashes after executing the side effect but before storing the key, the next retry will duplicate the work — true exactly-once requires combining idempotency keys with a transactional outbox or two-phase commit.

Enables safe client-side retries without risking duplicate charges, duplicate orders, or duplicate notifications in production systems handling payments or critical state changes.

Like a coat-check ticket for API requests — hand it in, get the same coat back even if you forgot whether you already dropped it off.

Idempotency keys + transactional outbox pattern for exactly-once semantics across distributed services