Idempotency
Also called idempotent, idempotency key.
The property of an operation that has the same effect whether it runs once or several times, so it is safe to retry.
Last updated
What it is.
In HTTP, RFC 9110 calls a method idempotent if several identical requests have the same intended effect as one. PUT and DELETE are idempotent by definition; POST is not. Setting a value to 5 is idempotent. Adding 5 is not.
For actions that are not naturally idempotent, such as charging a card, APIs use an idempotency key: a unique ID the client sends with the request. The server stores the result for that key and returns it again if the same key comes back, instead of charging twice.
Why it matters
Networks drop responses, users double-click and systems retry. Without idempotency, each retry can create a duplicate order, payment or email. Retries are built into webhooks, queues and mobile apps, so this matters everywhere money or messages move.
In a product build
We give every create action that matters an idempotency key, store keys with their results for a set period, and make queue consumers and ETL steps safe to re-run. Database unique constraints back this up, so duplicates fail even if code gets it wrong.
Common mistakes.
- 01
Generating a new key on each retry, which defeats the point.
- 02
Checking for duplicates in code without a unique constraint, which fails under load.
- 03
Treating the key as done before the action finishes, so a crash mid-way loses it.
Read the official text.
Primary sources this definition is based on.
- RFC 9110, HTTP Semantics, section 9.2.2 Idempotent Methods (IETF)checked 2026-10-25
Work it out with a tool.
Related terms.
- WebhookAn HTTP request one system sends to a URL you choose as soon as an event happens, so you do not have to keep asking.
- Message queueA buffer that holds messages, such as tasks or events, until a worker is ready to process them, so the sender does not have to wait.
- Event-driven architectureA way of designing software where parts of the system publish events about what happened, and other parts react to them on their own.
- Rate limitingCapping how many requests a user, API key or address can make in a given time, to protect a system and share capacity fairly.
- ETL (extract, transform, load)A data pipeline that pulls data out of source systems, cleans and reshapes it, and loads it into a destination such as a data warehouse.
Guides and pages
Browse the full glossary or read answers to common questions.
