How do idempotency keys work?

The client generates a unique key (UUID) and includes it in the request header. The server checks if it has already processed a request with that key. If yes, it returns the cached response. If no, it processes the request and stores the key with the response for future lookups.

Is idempotency the same as being safe?

No. A "safe" HTTP method (GET, HEAD, OPTIONS) has no side effects. An "idempotent" method may have side effects on the first call but produces the same result on subsequent calls. PUT is idempotent but not safe (it modifies data). GET is both safe and idempotent.

How long should I store idempotency keys?

Typically 24-48 hours. This covers retry windows for most use cases. Stripe stores idempotency keys for 24 hours. Use Redis with a TTL for efficient, self-cleaning storage.

Idempotency Explained

The property that makes distributed systems resilient — operations that are safe to retry, no matter how many times.

Idempotency

Idempotency is the property of an operation where performing it multiple times produces the same result as performing it once. In distributed systems, idempotent operations are essential for safely retrying failed requests without causing duplicate side effects like double charges or duplicate records.

Explanation

In a perfect network, every request succeeds on the first attempt and produces exactly one result. In reality, networks are unreliable — requests time out, connections drop, responses get lost. When a client does not receive a response, it cannot know whether the server processed the request or not. The safe thing to do is retry, but if the operation is not idempotent, retrying could create duplicate records, charge a credit card twice, or send an email again. Idempotent operations are safe to retry. HTTP GET, PUT, and DELETE are naturally idempotent by specification. GET returns the same data regardless of how many times it is called. PUT replaces the entire resource — calling it twice with the same data leaves the same result. DELETE removes a resource — calling it again on an already-deleted resource is a no-op. HTTP POST is not idempotent by default — each call typically creates a new resource. Making POST operations idempotent requires an idempotency key — a unique identifier (UUID) that the client generates and includes in the request. The server checks if it has already processed a request with that key; if so, it returns the cached response instead of processing again. Stripe, PayPal, and most payment APIs support idempotency keys for this reason.

Bookuvai Implementation

Bookuvai enforces idempotency in all critical write operations — payment processing, order creation, email sending, and webhook handling. Our standard API patterns include idempotency key support on POST endpoints, with processed keys stored in Redis with a 24-hour TTL. This ensures that network retries, webhook redeliveries, and client-side retry logic never cause duplicate side effects.

Key Facts

HTTP GET, PUT, and DELETE are naturally idempotent; POST is not
Idempotency keys (client-generated UUIDs) make POST operations safe to retry
Essential for payment processing — prevents double charges

Related Terms

Frequently Asked Questions

How do idempotency keys work?: The client generates a unique key (UUID) and includes it in the request header. The server checks if it has already processed a request with that key. If yes, it returns the cached response. If no, it processes the request and stores the key with the response for future lookups.
Is idempotency the same as being safe?: No. A "safe" HTTP method (GET, HEAD, OPTIONS) has no side effects. An "idempotent" method may have side effects on the first call but produces the same result on subsequent calls. PUT is idempotent but not safe (it modifies data). GET is both safe and idempotent.
How long should I store idempotency keys?: Typically 24-48 hours. This covers retry windows for most use cases. Stripe stores idempotency keys for 24 hours. Use Redis with a TTL for efficient, self-cleaning storage.