Idempotent

An operation is idempotent if performing it once or many times leaves the system in the same state. Setting a value is idempotent; adding to it is not.

Why it matters

Networks fail and clients retry. If a request timed out, the client cannot know whether the server processed it. When the operation is idempotent, retrying is safe; when it is not, a retry can charge a customer twice. In HTTP, GET, PUT and DELETE are defined as idempotent, while POST is not.

Example

PUT /users/42/email      {"email": "a@example.com"}   -> idempotent
POST /payments           {"amount": 500}              -> not idempotent

For payments, APIs often accept an idempotency key:

POST /payments
Idempotency-Key: 7c1d-4e9a

If the same key arrives twice, the server returns the first result instead of charging again.

Common mistakes

• Assuming DELETE is not idempotent because the second call returns 404; the resulting state is still the same.
• Making a retried POST create duplicate records because no unique key is checked.
• Confusing idempotent with safe; DELETE is idempotent but not safe, since it changes data.

Related

• REST API
• Webhook
• Race condition
• HTTP status code

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.