Skip to content
BENIBIX Learn

Idempotency

Development🔌 APIsAPI Design Practices

Also known as Idempotent, Idempotency Key, Idempotent Request

When doing something twice has the same result as doing it once.

Think of it like

Think of it like a lift button. Pressing it five times calls the lift once.

Example

Emma's app sends a payment with an idempotency key. The network drops, the app sends it again, and the card is charged only once.

Why it matters

Networks fail all the time. Idempotent actions turn a scary retry into a safe one.

Definition

An action is idempotent when doing it twice gives the same result as doing it once. In HTTP, GET, PUT and DELETE are meant to work this way, and POST is not. This matters when a network drops and a client cannot tell if a request arrived. If the action is safe to repeat, the client can just send it again. Payment APIs add a special key to each POST, so a retry never charges twice.

Example code

http
POST /payments HTTP/1.1
Idempotency-Key: 8f2c-41a7

{"amount": 2500}
The same key on a retry tells the server it has seen this payment.

Common mistake

Sending a POST again with no key to mark it. One lost answer becomes two orders.

Key takeaways

  1. 1
    Twice equals once. Same end result.
  2. 2
    GET, PUT, DELETE. Meant to be idempotent.
  3. 3
    Keys for POST. Make retries safe.