HTTP Methods and Idempotency: What RFC 9110 Actually Promises
A mobile client sends POST /payments, the connection drops before the response arrives, and the app retries. Did the customer just pay twice? HTTP can't tell you, because POST makes no promise about repeats. PUT and DELETE do. That promise is called idempotency, and together with "safe" and "cacheable" it's most of what the method name in a request line actually means.
All of this is defined in RFC 9110, the current HTTP semantics spec. PATCH lives in RFC 5789, and a newcomer, QUERY, got its own RFC this year.
Three properties, defined properly
RFC 9110 section 9.2 gives the definitions:
- Safe (9.2.1): a method is safe if its defined semantics are "essentially read-only". The client isn't asking for any state change. GET, HEAD, OPTIONS and TRACE are safe.
- Idempotent (9.2.2): a method is idempotent if "the intended effect on the server of multiple identical requests" is the same as the effect of one. PUT, DELETE and all the safe methods qualify.
- Cacheable (9.2.3): a response can be stored and reused only if the method allows it. RFC 9110 defines caching for GET, HEAD and POST, and notes that most caches only implement GET and HEAD.
Every safe method is idempotent, since doing nothing twice is still nothing. The reverse isn't true: DELETE changes state, but deleting the same thing twice leaves the server where one delete did. Our HTTP method reference shows these flags per method with sample requests, if you want a quick lookup. It predates QUERY, and it shows POST as cacheable only with explicit freshness information, which the spec allows but almost no cache implements.
Idempotent means effect, not response
The most common misunderstanding: people expect an idempotent request to return the same response every time. It doesn't have to.
DELETE /api/carts/42/items/7 HTTP/1.1
→ 204 No Content
DELETE /api/carts/42/items/7 HTTP/1.1
→ 404 Not Found
Both requests intend "item 7 is not in cart 42". After either, it isn't. That's idempotent, even though the status changed. (Whether the second one should be 404 or 204 is a design choice; the status codes post has a decision table for those.)
Side effects outside the intended effect don't count either. RFC 9110 points out that a server can log every request, and the client "cannot be held accountable" for that. Incrementing a view counter on GET is fine. Deleting a record on GET is not, and the spec's example is a page?do=delete link, which anything that follows links with GET will trigger. Resource owners must not let a safe method trigger an unsafe action.
Retries are the whole point
The practical payoff is in 9.2.2. Idempotent requests can be repeated after a connection failure, because a repeat can't make things worse. For everything else, a client "SHOULD NOT automatically retry a request with a non-idempotent method unless it has some means to know" that repeating it is actually safe.
A proxy MUST NOT automatically retry non-idempotent requests at all. So when you write retry logic (or configure it in an HTTP client or service mesh), the method decides the default. GET, PUT and DELETE are fair game after a timeout. POST and PATCH need something extra.
PUT, PATCH and POST
PUT replaces the target's state with the enclosed representation. Sending the same full representation twice leaves the same state, which is why it's idempotent. Per 9.3.4, a PUT that creates a resource returns 201, one that modifies returns 200 or 204, and the server MUST NOT send a validator like ETag in the response unless the stored content is byte-for-byte what the client sent. PUT responses aren't cacheable.
PATCH sends "a set of instructions" for changing the resource, in RFC 5789's words, rather than a new version of it. That's why RFC 5789 says PATCH "is neither safe nor idempotent". A patch that sets email to a value is harmless to repeat; one that means "add 1 to quantity" or "append this item" isn't. RFC 5789 also lists the errors: 400 for a malformed patch document, 415 for an unsupported patch format (with an Accept-Patch header listing the ones you do support), 422 when the patch is valid but can't be applied, and 409 for conflicts.
POST asks the resource to process the content according to its own rules. It's the catch-all: creating a resource in a collection (201 with Location), running an action, submitting a form. No idempotency promise at all.
Making PATCH and PUT safe to race: If-Match
Idempotency handles repeats from one client. Two clients editing the same thing is a different problem, the lost update, and HTTP's answer is conditional requests. RFC 5789 recommends exactly this for PATCH: send a strong ETag in If-Match so the request fails if the resource changed since you read it.
PATCH /docs/7 HTTP/1.1
Content-Type: application/merge-patch+json
If-Match: "v1"
{"title": "Q4 plan"}
The body is JSON Merge Patch (RFC 7396): a member's new value replaces the old one and null removes it. If the current ETag isn't "v1", RFC 9110 section 13.1.1 has the server refuse with 412 Precondition Failed and not apply the change. A PATCH guarded this way is also safe to retry: if the first attempt landed, the ETag moved and the retry gets 412 instead of applying twice.
The mirror image is If-None-Match: * on a PUT. Section 13.1.2 describes it as a way to stop a PUT from overwriting a representation that already exists, so it means "create only".
Making POST retryable
You have two well-trodden options.
Let the client choose the ID and use PUT. If the client generates a UUID up front, PUT /orders/0b6f... is naturally idempotent, and adding If-None-Match: * makes a second attempt fail cleanly instead of overwriting. Any UUID generator or crypto.randomUUID() gives you the ID.
PUT /orders/0b6f2c1e-8a5d-4c1f-9d7e-3f0a2b4c6d8e HTTP/1.1
Content-Type: application/json
If-None-Match: *
{"sku": "BOOK-1", "qty": 1}
Keep POST and add an idempotency key. The client sends a unique key in a header; the server stores the first response under that key and replays it for retries. Stripe's API works this way: all v1 POST requests accept an Idempotency-Key header of up to 255 characters, Stripe suggests V4 UUIDs, keys can be pruned after they're at least 24 hours old, and a reuse with different parameters is an error. Stripe also says not to send keys on GET and DELETE, because those are idempotent by definition. The IETF is standardising the header in draft-ietf-httpapi-idempotency-key-header; as of November 2026 it's at revision -08 (updated 22 October 2026) and still an Internet-Draft, not an RFC. Storage design for keys deserves its own post, and the Stripe integration patterns post shows the client side.
Caching follows the method
GET and HEAD responses are cacheable by default unless Cache-Control says otherwise. POST responses are cacheable only when they include explicit freshness information and a Content-Location matching the request target, which almost nothing relies on. PUT, DELETE, OPTIONS and TRACE responses aren't cacheable. The HTTP caching headers post covers the directives themselves.
This used to force an awkward choice for complex searches: GET with a giant query string, or POST and give up caching and retries. RFC 9110 doesn't help with a GET body either; content in a GET request "has no generally defined semantics" and can enable request smuggling.
QUERY: the method that fills the gap
RFC 10008, "The HTTP QUERY Method", was published as a Proposed Standard in June 2026. QUERY carries the query in the request body, and the RFC states that QUERY requests are both safe and idempotent. Responses are cacheable, with the cache key required to "incorporate the request content". Servers must fail a QUERY whose Content-Type is missing or doesn't match the body, and can advertise support with an Accept-Query response header.
QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
q=foo&limit=10&sort=-published
That example is straight from the RFC. Support in frameworks, proxies, CDNs and HTTP clients will take time to arrive, so check every hop in your path before you depend on it. Until then, a POST search endpoint is fine as long as you document that it's safe and idempotent, and your own clients treat it that way.
A decision rule for new endpoints
| You want to... | Use | Retry after a timeout? |
|---|---|---|
| Read a resource | GET | Yes |
| Run a read-only search with a big body | QUERY where supported, else POST | Yes for QUERY; for POST only if you document it as safe |
| Replace a resource whose URL the client knows | PUT (+ If-Match for edits) | Yes |
| Create with a client-chosen ID | PUT + If-None-Match: * | Yes |
| Create in a collection, server picks the ID | POST + Idempotency-Key | Only with the key |
| Change a few fields | PATCH + If-Match | Yes with If-Match, otherwise no |
| Trigger an action (send, charge, deploy) | POST + Idempotency-Key | Only with the key |
| Remove a resource | DELETE | Yes |
If an endpoint can't be made idempotent and you can't add a key, say so in its docs, so nobody puts it behind an automatic retry.
Written by AIDToolStack Editorial
Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.
Sources
- www.rfc-editor.org/rfc/rfc9110.html
- www.rfc-editor.org/rfc/rfc5789.html
- www.rfc-editor.org/rfc/rfc7396.html
- www.rfc-editor.org/rfc/rfc10008.html
- datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/
- datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
- docs.stripe.com/api/idempotent_requests
Related Posts
Explore on AIDToolStack
Discover tools and servers featured in our directory.
AI Tools
MCP Servers
Sponsor Our Newsletter
Reach thousands of developers who are actively evaluating AI tools, MCP servers, and dev infrastructure. Our weekly newsletter goes to engaged technical decision-makers.
All sponsored content is clearly labeled per our editorial policy.