Idempotency keys attach a unique key to a POST request to enable deduplication, allowing repeated requests to return the same result without re-performing the operation.

Idempotency means an operation yields the same result when run multiple times as with a single execution; GET requests are inherently idempotent, while POST requests typically are not.

Idempotency keys prevent duplicate mutating requests (POST, PATCH, DELETE) by caching and reusing the first response when the same key is sent again.

Key decision points include applying the mechanism only to mutating methods, not caching 500 errors, and using a 24-hour TTL to balance retry windows with cache size.

Edge cases: if payload differs with the same key, decide between erroring (e.g., Stripe-style 422) or returning the cached result; potential failure between charging and caching can lead to duplicate charges without a transactional guarantee; prefix keys with user/account IDs to avoid cross-user collisions in multi-tenant systems.

Important client guidance: generate a UUID per logical operation and reuse the same key across retries; do not generate a new key inside the retry loop.

A minimal Node.js/Express and Redis example shows how to implement an idempotency middleware, including TTL, caching responses, and avoiding caching 500 errors.

Server-side implementation example (Node.js with Express and Redis): check for key, use a distributed lock to prevent concurrent execution, process the operation once, cache the full response, and return cached responses on retries.

Header convention guidance notes Idempotency-Key as the recommended header name, with other headers like X-Idempotency-Key or X-Request-ID being used in various ecosystems.

Bottom line: idempotency keys are a lightweight, powerful pattern for making APIs that process payments or create records more reliable and user-trustworthy, with a simple middleware footprint and a single header change on the client.

Stripe popularized the pattern in 2013, demonstrating how an Idempotency-Key ensures a single charge even if requests are retried due to network issues or user impatience.

When to use: apply idempotency keys to non-idempotent endpoints where duplicate execution would cause real harm (payments, email sending, provisioning, inventory deductions, financial transfers); avoid on read-heavy or already-idempotent endpoints.