What is Idempotency

An idempotent operation produces the same result whether you call it once or multiple times. Calling PUT /users/42 {"name": "Alice"} ten times leaves the user's name as "Alice" — the same as calling it once. Calling POST /orders ten times creates ten orders — not idempotent.

How it works

In HTTP, the idempotent methods are GET, PUT, DELETE, and HEAD. Calling DELETE /users/42 once deletes the user. Calling it again returns 404 (already deleted) — the server state is the same. POST is not idempotent because each call typically creates a new resource.

For non-idempotent operations that need retry safety (e.g., payments), APIs use idempotency keys: the client sends a unique key with each request (Idempotency-Key: abc123). The server stores the result for that key and returns the same response on retries, preventing duplicate side effects.

Why it matters

Idempotency makes APIs safe to retry. Networks are unreliable — requests time out, responses get lost, clients retry automatically. If an operation is idempotent, retrying it is harmless. If it's not (like creating a payment), you need idempotency keys to prevent double-charging. Understanding which operations are idempotent drives correct error handling and retry logic.

See How REST Works for HTTP verbs and their idempotency properties.