🧾Idempotency Key

NEW

A unique client-supplied token allowing safe retries by ensuring the server processes a given request only once.

DESCRIPTION

Idempotency keys prevent duplicate effects from retried non-idempotent requests (e.g., payments, bookings). Clients generate a unique key per operation and send it with the request; the server stores responses keyed by that value. On retry, the server returns the original response instead of repeating the action. Keys typically expire and are scoped to endpoints and request bodies to avoid collisions. Idempotency complements retries, backoff, and at-least-once delivery semantics in distributed systems.

ALTERNATIVE DEFINITIONS

Stripe

Idempotency keys are unique identifiers that you add to requests. They guarantee that the API only performs an action once, even if the same request is received multiple times.

Focuses on API-level guarantees against duplicate operations.

Source

IETF Internet-Draft

The Idempotency-Key HTTP header field can be used to make non-idempotent HTTP methods idempotent.

Defines a standardized HTTP header for idempotency semantics.

Source

Shopify

Idempotent requests prevent duplicate operations by using idempotency keys to identify unique operations.

Explains practical API usage across retries to avoid duplicates.

Source

RELATED TERMS

Idempotence Retry Policy Exactly-Once Processing Entity Matching ETag At-Least-Once Delivery Distributed Transactions

COMPETING TERMS

Optimistic Concurrency Control

RELATIONS

• Broader: Key

KNOWLEDGE AREAS

Software Engineering Data Integration & Interoperability Data Security Platform & Tooling

TARGET AUDIENCE

Software Developer Solution Architect DevOps Engineer Software Architect Data Engineer

EXTERNAL SOURCES

• Wikipedia - Idempotence
• Stripe - API design guidance for idempotency
• IETF - Proposed Idempotency-Key HTTP header
• IETF RFC 7231 - HTTP idempotent method semantics

TOP QUESTIONS

Why are Idempotency Keys important for APIs?

They ensure safe retries for non-idempotent operations like charges or orders, preventing duplicate processing and improving reliability under network failures.

Category: Relevancy

How should servers store Idempotency Keys?

Store a mapping from key to request fingerprint and response, with TTL-based expiry. Ensure atomic upsert to avoid race conditions.

Category: Implementation

What’s a good scope for Idempotency Keys?

Scope keys to the endpoint and normalized request body. This avoids accidental reuse across different operations or payloads.

Category: BestPractice

How do Idempotency Keys interact with at-least-once delivery?

They provide exactly-once effects at the application layer by deduplicating retries, complementing at-least-once transport semantics.

Category: Concepts

Can Idempotency Keys expire?

Yes. Expire after a reasonable window (e.g., 24–72 hours) to bound storage while covering typical retry horizons.

Category: Operations

What happens if the same Idempotency Key is reused with a different payload?

Servers should reject with a conflict error, returning the original response or indicating a payload mismatch to prevent unintended operations.

Category: Risks

How are Idempotency Keys generated?

Clients generate high-entropy unique identifiers (UUIDs) per operation; avoid sequential or guessable values.

Category: Requirements

Do all HTTP methods need Idempotency Keys?

Typically only non-idempotent methods like POST benefit. PUT and DELETE are idempotent by definition, though keys may still help in practice.

Category: Opinion

What are common mistakes with Idempotency Keys?

Using short TTLs, not scoping by endpoint, and non-atomic storage can reintroduce duplicates or inconsistencies.

Category: Mistakes