Idempotency: definition and why it matters
An operation is idempotent when performing it several times has the same effect as performing it once. Reading a record or setting a status to “paid” is naturally idempotent; creating an order or sending an email is not, unless the system recognizes the repeat. APIs often handle this with an idempotency key: a unique identifier sent with the request so the server can detect and ignore duplicates.
Definition written by Alex Dionisio, Senior Product Manager. Updated November 13, 2026.
Why it matters for a PM
Networks fail, users double-click, webhooks get retried and AI agents call a tool again after an error. Without idempotency, each of these becomes a double charge, a duplicate ticket or two emails to the same customer. For every action with side effects, a PM should ask what happens if it runs twice, and make the answer part of the spec.
Example
A user taps “Pay” on a slow connection and nothing seems to happen, so they tap again. Because the app sends the same idempotency key with both requests, the payment provider recognizes the second one as a repeat and returns the result of the first. The customer is charged once.
Key points
- In HTTP, GET, PUT and DELETE are defined as idempotent; POST is not by default.
- An idempotency key lets a client retry safely after a timeout without knowing whether the first attempt went through.
- Webhook handlers record the IDs of processed events to skip duplicates.
- Agent tools with side effects need the same protection, since models retry.
Common mistakes
- Assuming retries are too rare to matter.
- Generating a new idempotency key on each retry, which defeats its purpose.
- Disabling the button as the only protection against double submission.
Go further with Module
The courses and lessons that cover this concept:
Guides on this topic
- Write a spec for an AI coding agent
The sections of a spec a coding agent can execute without guessing, with a SPEC.md template.
- MCP for Product Managers
Connect AI to your tools and scope an MCP server: tools, permissions, security, with a spec template.
- MCP vs API: the difference
When to expose an API, an MCP server or both, and what it changes for your product.