# What is Idempotency?

Also called idempotent operation, idempotency key.

An operation is idempotent when performing it more than once has the same effect as performing it once. This property matters whenever a request might be delivered twice, because a network failure often leaves the caller unsure whether the first attempt succeeded. Idempotency is what makes a safe retry possible without creating duplicates.

In HTTP, GET, PUT, and DELETE are defined as idempotent while POST is not, which is why creating a resource with POST twice produces two resources. Services solve this with an idempotency key. The client generates a unique identifier for each logical operation and sends it with the request, and the service returns the original result if it ever sees that key again.

Retries are everywhere in agent systems: rate limit backoff, timeouts, tool call retries, webhook redelivery, and workflow replays. Any one of them can execute a tool twice. If that tool sends an email, charges a card, or opens a ticket, a design that is not idempotent turns an ordinary transient failure into a duplicate that the user sees and remembers.

Idempotent is not the same as safe. A safe operation has no side effects at all, such as a read, while an idempotent one may have effects but converges to the same end state. Setting a value to true is idempotent, whereas incrementing a counter is not. It is also not the same as deduplicating after the fact, though a deduplication store is a common way to achieve it.

Practical rules follow from this. Prefer operations that set an absolute state over ones applying a relative change, derive keys deterministically from the logical operation rather than randomly per attempt, store keys long enough to outlast the longest retry window, and return the original response on a repeat rather than an error, so callers need no special handling.

## Key points

- Repeating the operation produces the same result as doing it once.
- GET, PUT, and DELETE are idempotent in HTTP, while POST is not.
- Idempotency keys let a client safely retry a creating request.
- Safe means no side effects, idempotent allows effects that converge.
- Prefer setting absolute state over applying relative changes.

## In practice

A workflow sends an onboarding email, then the service call times out after the message was already queued. On retry, the tool sends the same idempotency key, derived from the user identifier and the email type. The provider recognizes the key, skips sending, and returns the original message identifier. The user receives one email rather than two, and the workflow continues as though nothing had gone wrong.

## Related terms

- [Webhook](/en/glossary/webhook)
- [Rate Limiting](/en/glossary/rate-limiting)
- [REST API](/en/glossary/rest-api)
- [Tool Calling](/en/glossary/tool-calling)
- [API](/en/glossary/api)

[Back to the AI Glossary](/en/glossary)