Pattern · seen in 6 breakdowns across 5 companies

Idempotency Keys

consistency

Definition

A client-supplied stable identifier that the server uses to deduplicate retries of the same logical operation. The first request creates a record of the outcome under the key; subsequent requests with the same key return that recorded outcome rather than re-executing the work. Same key in, same outcome out, regardless of how many times the request is sent.

Idempotency keys are the user-facing contract that makes safe retry possible. They sit above the wire protocol -- the network can drop, the server can crash, the client can time out and retry, and as long as both sides agree on the key, the outcome is deterministic. The implementation underneath (atomic phase commits, dedup storage, etc.) is a separate concern; the pattern is the agreement on the identifier.

When it applies

01Any non-idempotent operation that may be retried -- payment charges, resource creation, irreversible state changes.
02APIs where the caller is responsible for retry policy and the server cannot trust the network.
03Workflows that span multiple systems where partial completion on retry would diverge state.

Tradeoffs

Requires durable storage of (key -> outcome) records with TTLs that outlive realistic retry windows.
Adds per-request bookkeeping cost: every request reads and (on first execution) writes a key record.
Key reuse is a real hazard -- a client that reuses an old key for a new logical operation gets the old outcome, silently. Key generation discipline (UUIDs, monotonic IDs, scope-prefixed) becomes part of the contract.

The same move, 6 ways

Every row is a production system that bet on this pattern — the note says how, in that system's own terms.

Shopify
Shopify Engineering
2022
Shopify's instantiation is provider-side: the centralized payment service tracks each attempt's completed steps under the key and runs recovery steps to rebuild state before continuing, so a retry never re-reaches the financial partner. The ULID key format makes the key itself index-friendly - a 50% INSERT duration reduction in one high-throughput system. Read the breakdown →
Amazon (AWS)
Amazon Builders' Library
2021
The caller attaches a unique identifier to a request, and the service treats any later request carrying the same identifier as the same request, so a retry replays the first outcome instead of doing the work twice. Stripe, Shopify, and Airbnb have all appeared in the library making this call from the client-facing side; AWS's piece is the platform provider's view of the same contract (EC2 calls the identifier a ClientToken). The reason a caller-supplied key beats a hash of the request is intent: identical parameters don't mean identical intent, and only the caller knows whether a second identical request is a mistaken duplicate or a genuine second order. Read the breakdown →
Amazon (AWS)
Amazon Builders' Library
2019
EC2 RunInstances' client token is the same mechanism Stripe exposes as the Idempotency-Key header: the client names the operation, retries repeat the name, and the server deduplicates — converting an unsafe-to-retry, side-effecting call into a safe one. Second company, same contract: retry safety is purchased at API-design time. Read the breakdown →
Airbnb
Airbnb Engineering
2019
This is the deepest look the library has at what an idempotency key actually does inside a service. Stripe defines the key as an API contract, Shopify shows why it matters at volume, and AWS pairs it with retry discipline; Airbnb shows the interior. Here the key is three things at once: the row a request locks while it runs, the value the tables are sharded on, and a design decision in its own right, since a random UUID per request behaves differently from a deterministic key like payment-1234-refund (which lets a given refund happen only once, ever). Read the breakdown →
Segment
Segment Blog
2017
The furthest the pattern reaches from where it started: no contract, no stored response replayed, no request/response boundary at all. The messageId (a client-generated unique ID, chosen over more complex schemes to keep the client's job as close to nothing as possible) doubles as the routing key, the primary key, and the identity in a pipeline-wide dedupe ledger that settles the ambiguity downstream because the boundary can't. Across five companies the same key has been a contract term (Stripe), a client discipline (Shopify), a piece of server interior (Airbnb), a platform default (AWS), and here, pure infrastructure - one idea seen from five distances. Read the breakdown →
Stripe
Stripe Engineering
2017
This is where the pattern gets its clearest early statement: a client-generated unique ID sent with each mutating request (Stripe's Idempotency-Key header on all POST endpoints). That one key lets the server handle all three network-failure cases: process a fresh request, pick up and finish an interrupted one, or replay the saved result of one that already completed. The same key going in always produces the same outcome coming out. Read the breakdown →

Often used together

Patterns sharing breakdowns with this one — derived from co-occurrence, threshold ≥2 shared.

retry-with-backoff-and-jitter ×3atomic-phases ×2retryable-error-classification ×2

Problems this pattern answers

The walls where its breakdowns live — each opens the cross-company comparison.

Ambiguous failure under retryAIRBNB · AMAZON (AWS) · SEGMENT · SHOPIFY · STRIPE →Retry-amplified overloadAMAZON (AWS) →