APIs & Authentication
What is idempotency?
A property of an operation where running it multiple times produces the same result as running it once, critical for safe retries in distributed systems.
Also known as: idempotency
An operation is idempotent if calling it twice (or N times) leaves the system in the same state as calling it once. Setting a user's email to alice@example.com is idempotent; charging $10 to a credit card is not. The distinction matters because networks fail mid-request: if you do not know whether the server processed your call, you have to either retry (and risk duplication) or give up (and risk losing work).
HTTP bakes idempotency into its method semantics. GET, PUT, and DELETE are defined as idempotent; POST and PATCH typically are not. That is why retry-on-failure is safe with PUT but dangerous with POST, and why payment APIs (Stripe, Square, Adyen) all support an Idempotency-Key header: the server stores the result of the first call under that key and returns the cached result on every retry.
Building idempotent endpoints often comes down to one question: what is the natural unique key for this operation? An order create that takes a client_order_id is naturally idempotent. A payment that takes an idempotency_key is explicitly so. Without one, you are stuck deduplicating after the fact.
In the wild
- →Stripe accepting an
Idempotency-Key: abc123header so a retried charge does not double-bill - →A REST API returning the same response on a duplicate PUT because the resource state is unchanged
- →A queue worker designed to be safely retried because every step writes a row with a deterministic primary key
How Brand.dev uses idempotent
Endpoints in the Brand.dev API where this concept comes up directly.
FAQ
Which HTTP methods are idempotent?
GET, HEAD, OPTIONS, PUT, and DELETE are defined as idempotent. POST and PATCH are not; if you need them to be, your server must implement deduplication, often via an idempotency key.
How do idempotency keys work?
The client generates a unique key per logical operation and sends it on every retry. The server stores the response keyed by that string for some TTL; subsequent calls with the same key return the stored response without re-executing.
Is idempotency the same as safety?
No. A safe method does not modify state at all (GET). An idempotent method may modify state, but doing it twice has the same effect as once.
Related terms
An API that follows REST conventions, using HTTP methods on resource URLs to model create/read/update/delete operations.
The application protocol the web is built on, a simple request/response format for asking a server for a resource.
An Application Programming Interface, a contract that lets one program request actions or data from another in a stable, documented way.
A user-defined HTTP callback, your URL gets POSTed to whenever an event happens in someone else's system, instead of you polling for changes.