# Idempotent

> Learn what idempotent means in HTTP. Understand why GET, PUT, and DELETE are idempotent, why POST is not, and how idempotency affects API design.

Source: https://howhttpworks.com/glossary/idempotent
Last reviewed: 2026-10-05

> **TL;DR:** An HTTP method is idempotent when sending the same request twice has the same intended effect on the server as sending it once. GET, HEAD, OPTIONS, TRACE, PUT and DELETE are idempotent; POST and PATCH aren't guaranteed to be. The responses to each attempt are allowed to differ.

## The Core Idea

Say an API takes replacement text at a known URL:

```bash
curl -i -X PUT 'https://api.example.com/documents/notes' \
  -H 'Content-Type: text/plain' --data-binary 'Reviewed'
```

Send it twice and the document ends up with the same text either way. The first response might be 201 and the second 204. Idempotency is about the end state, not the status codes.

[RFC 9110 §9.2.2](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2) scopes the guarantee to the effect the user asked for. The server is free to log every request or keep a revision history.

## Safe And Idempotent Are Not The Same

A safe method is one where the client isn't asking for any state change. GET, HEAD, OPTIONS and TRACE are defined as safe, and they're idempotent too. PUT and DELETE are idempotent but not safe, because changing state is the whole point of them.

A GET that returns a different price tomorrow is still idempotent. The client never asked for the price to change.

## Why APIs Care About This

When a connection drops before the response arrives, the client can't tell whether the server committed the write. With an idempotent method, it can just retry without multiplying the effect. A plain POST that creates an order gives you no such promise from the protocol.

Idempotency only covers repeats. A retry may fail, someone else may edit the resource between your attempts, and concurrent writes may conflict. Use [If-Match](https://howhttpworks.com/headers/if-match) for version-sensitive writes, and follow the API's documented retry policy for POST.

## Common Examples

| Request | Effect of an identical repeat |
| --- | --- |
| `GET /documents/notes` | Retrieve again; newer content is possible. |
| `PUT /documents/notes` with the same text | Set the same desired representation. |
| `DELETE /documents/notes` | Keep the target removed; a repeat can return 404 after the first 204. |
| `POST /orders` | Can create another order unless the API deduplicates it. |

These assume nobody else recreates or changes the target between attempts.

## PATCH Needs Extra Care

A merge patch that sets `{"status":"archived"}` is idempotent. A JSON Patch `add` targeting `/tags/-` appends a new element every time it runs. The patch format and its operations decide the effect, not the PATCH method itself.

A POST endpoint can add deduplication at the application level with an [idempotency key](https://howhttpworks.com/glossary/idempotency-key). The server has to implement it; sending the header to an endpoint that doesn't changes nothing.

## Related

- [HTTP Method](https://howhttpworks.com/glossary/method)
- [PATCH](https://howhttpworks.com/methods/patch)