Idempotency
eye-dem-POH-ten-see
The property where performing an operation multiple times produces the same result as performing it once.
Idempotency means you can do the same thing twice (or ten times) and get the same result as doing it once. If you send a "create payment" request twice with the same idempotency key, you get one payment, not two. If you apply the same database migration twice, the schema does not break. The operation is safe to retry.
This matters because networks are unreliable. Your application sends a request to charge a customer. The request reaches the server and the charge succeeds, but the response gets lost due to a network timeout. Your application does not know if the charge went through. Without idempotency, retrying means the customer gets charged twice. With idempotency, retrying is safe because the server recognizes the duplicate and returns the original result.
Stripe popularized idempotency keys in their API. You send a unique key (usually a UUID) with each request. If Stripe sees the same key again within 24 hours, it returns the cached response instead of processing the request again. This pattern has become standard practice for any API that handles money, creates resources, or produces side effects.
Examples
A payment system handles duplicate charges.
A customer clicks 'Pay Now' and the request times out. The frontend retries. Without idempotency, the customer gets charged $49.99 twice. With idempotency, the second request includes the same idempotency key. Stripe recognizes it, skips processing, and returns the result of the first charge. The customer is charged exactly once.
A message queue processes the same message twice.
The queue delivers a 'send welcome email' message. The worker sends the email and tries to acknowledge the message, but the acknowledgment fails. The queue redelivers the same message. Without idempotent handling, the user gets two welcome emails. With idempotency, the worker checks a 'sent emails' table, sees this email was already sent, and skips it.
A database migration is designed for idempotent execution.
The migration adds a 'status' column to the orders table. Instead of 'ALTER TABLE orders ADD COLUMN status,' it uses 'ALTER TABLE orders ADD COLUMN IF NOT EXISTS status.' Running the migration twice does not fail. Running it three times produces the same result as running it once. This is critical for deployment systems that might retry migrations.
In practice
Read more on the blog
Frequently asked questions
Which HTTP methods are idempotent?
GET, PUT, and DELETE are idempotent by design. GET returns the same data no matter how many times you call it. PUT replaces a resource with the same data each time. DELETE removes a resource; deleting it again does not remove it twice. POST is not idempotent by default: each POST can create a new resource. That is why APIs use idempotency keys with POST requests, to make them safe to retry.
How do you implement idempotency in your own API?
Accept an idempotency key header (usually a UUID). Before processing the request, check if that key exists in your database. If it does, return the stored response. If not, process the request, store the response keyed by the idempotency key, and return it. Set an expiration (24-72 hours) on stored keys so your table does not grow forever. Use a database unique constraint on the key to prevent race conditions from concurrent requests.
Related terms
Application programming interface: a defined way for software programs to communicate with each other.
An HTTP callback that sends data to your application automatically when an event occurs in another system.
A system that stores and delivers messages between services, allowing asynchronous communication.
Representational State Transfer: an architectural style for building web APIs using HTTP methods.
A design pattern where systems communicate by producing and consuming events instead of direct calls.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.