Idempotent Request
Also known as: Idempotent Operation, Safe Retry
An API request designed so that making it multiple times produces the same result as making it once — safe to retry without side effects.
Definition
An idempotent request is an API operation designed so that repeating it produces the same result as executing it once. If the same idempotent request is sent twice (or 50 times), the outcome is identical to having sent it once — no duplicate records created, no double-charges, no double-notifications.
Idempotency is essential for reliable distributed systems. Network failures cause retries; without idempotency, every retry risks creating duplicate side effects. With idempotency, retries are safe — if you don't get a confirmation that the first request succeeded, you can retry without fear of double-application.
Common patterns for achieving idempotency: idempotency keys (client-generated unique IDs that the server uses to detect and de-duplicate retried requests), checking before acting (read the current state and only update if needed), and using HTTP methods correctly (GET, PUT, and DELETE are naturally idempotent; POST typically isn't unless you implement it explicitly).
Why It Matters
Idempotency is what makes distributed systems reliable. Network failures, server crashes, and timeouts all create retry scenarios. Without idempotency, a retried payment request creates a double-charge; a retried email send creates duplicate emails; a retried CRM update overwrites data. Idempotency turns these scenarios into safe no-ops.
The biggest mistake is assuming HTTP methods provide idempotency automatically. GET and PUT are idempotent if your handler implements them correctly; POST typically isn't unless you add idempotency keys. Many APIs document themselves as 'POST creates a resource' without explaining how to handle retries safely.
Examples in Practice
Stripe's API uses idempotency keys: the client generates a unique key (e.g., `key_purchase_123`) and includes it in the request header. If the request is retried with the same key, Stripe recognizes it and returns the original response without re-executing — preventing accidental double-charges.
A CRM webhook receiver uses event IDs to ensure idempotency: when the same webhook event fires twice (due to retry), the receiver checks if the event ID has already been processed. If yes, returns success without re-applying the update. If no, processes and records the event ID.
An email send API requires an idempotency key on each request. If the calling system retries due to a timeout, the duplicate request returns the original send result instead of sending the email twice. Without idempotency, network flakiness would generate duplicate emails to recipients.