Idempotency in REST APIs: Safe to Retry?

Why it exists

Networks are unreliable. A client might send a request, but the connection drops before the response arrives. The client doesn't know if the server processed the request. Idempotency provides a contract that allows the client to safely retry certain operations without causing unintended side effects.

The mental model

Think of idempotency as the difference between setting a value and incrementing it. Setting a thermostat to 70 degrees is idempotent; you can do it once or ten times, and the final temperature setting is still 70. Pressing the "+" button ten times is not; each press changes the state. In APIs, PUT /thermostat/temp with a body of {"value": 70} is idempotent. POST /thermostat/increment is not.

How it works

The HTTP specification defines the expected behavior for its methods. Safe, read-only methods like GET, HEAD, and OPTIONS are inherently idempotent. PUT is idempotent because it's defined as "create or replace"; sending the same PUT request multiple times just overwrites the resource with the same data. DELETE is idempotent because after the first successful request, the resource is gone, and subsequent requests do nothing to change that state. In contrast, POST and PATCH are not idempotent. A POST typically creates a new resource, so multiple requests create multiple resources.

When to use it

You rely on idempotency when building resilient clients. If a request for an idempotent method (PUT, DELETE) times out or fails with a network error, you can automatically retry it. This is fundamental to building reliable distributed systems where transient network failures are common. The server is responsible for implementing this behavior correctly.

When not to use it

You must not automatically retry non-idempotent methods like POST. Retrying a POST to a /payments endpoint could charge a customer multiple times. For these operations, you need a different strategy, such as generating a unique idempotency key in the request header that the server can use to recognize and discard duplicate requests.

One canonical example

A client sends DELETE /users/123. The request succeeds, the server deletes user 123, and sends a 200 OK response. The network fails, and the client never receives the response. The client, unsure of the outcome, sends the exact same DELETE /users/123 request again. This time, the server sees the user is already gone and returns a 404 Not Found. Despite two different responses (200 and 404), the server's state is correct and consistent: user 123 is deleted. This is idempotency in action.