Glossary Term
Idempotent
Learn what idempotent means in HTTP. Understand why GET, PUT, and DELETE are idempotent, why POST is not, and how idempotency affects API design.
TL;DR: Idempotent does not mean “nothing happens.” It means repeating the same request should leave the system in the same intended end state.
Idempotency matters because networks are messy. Connections time out, proxies retry, clients lose the response, and job runners re-send work. When that happens, the safest requests are the ones you can repeat without creating extra damage.
The Core Idea
An operation is idempotent if:
- the first request may change state
- repeating that exact request should not keep changing state further
That is why idempotency is about the final result, not the absence of side effects.
For example, this can be idempotent:
PUT /users/42
{"name":"Avery"}Sending it twice should still leave the user named Avery.
Safe And Idempotent Are Not The Same
People mix these up a lot.
- safe means the request should not change server state as part of normal use
- idempotent means repeating it should not change the final outcome after the first success
Examples:
GETis safe and idempotentPUTis not safe, but is idempotentPOSTis usually neither
That distinction matters when you reason about retries and automation.
Why APIs Care About This
Idempotency is a practical API design tool:
- clients can retry timeouts more confidently
- workers can survive duplicate deliveries
- operators can re-run commands with less fear
- load balancers and intermediaries can behave more predictably
That is why “is this operation idempotent?” is often really a reliability question.
Common Examples
GET /users/42: reading again does not change anythingPUT /users/42: replacing with the same representation again lands in the same stateDELETE /users/42: once the resource is gone, repeating the delete should keep it gone
By contrast, POST /orders is usually non-idempotent because sending it twice may create two orders.
PATCH Needs Extra Care
PATCH is the method that causes the most confusion here.
- “set
statustoarchived” can be idempotent - “increment
countby 1” is not
So PATCH is not automatically non-idempotent. It depends on the patch semantics you define.
Related terms: HTTP Method, HTTP Request, HTTP Response
Frequently Asked Questions
What does idempotent mean in HTTP?
An idempotent request reaches the same intended final state whether it runs once or multiple times.
Which HTTP methods are idempotent?
GET, HEAD, PUT, DELETE, and OPTIONS are defined as idempotent. PATCH may be idempotent, but only if you design it that way.
Why is idempotency important?
It makes retries safer. If a client is unsure whether the first attempt succeeded, it can repeat an idempotent request without multiplying side effects.
Is DELETE always idempotent?
Yes in the HTTP sense, because repeating the delete should leave the resource in the same final state: gone.