Skip to content
Tutorials

HTTP Methods and Idempotency: What RFC 9110 Actually Promises

AIDToolStack EditorialNovember 7, 20267 min read
HTTPRESTAPI DesignIdempotency
Share:Twitter

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.
Matrix of HTTP methods against safe, idempotent and cacheable: GET and HEAD are all three; OPTIONS and TRACE are safe and idempotent; QUERY is safe, idempotent and cacheable; PUT and DELETE are idempotent only; POST is none except limited cacheability; PATCH is none
Matrix of HTTP methods against safe, idempotent and cacheable: GET and HEAD are all three; OPTIONS and TRACE are safe and idempotent; QUERY is safe, idempotent and cacheable; PUT and DELETE are idempotent only; POST is none except limited cacheability; PATCH is none

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.

Sequence diagram: clients A and B both GET /docs/7 and receive ETag v1; A sends PUT with If-Match v1 and gets 200 with ETag v2; B sends PUT with If-Match v1 and gets 412 Precondition Failed, then re-reads, merges and tries again
Sequence diagram: clients A and B both GET /docs/7 and receive ETag v1; A sends PUT with If-Match v1 and gets 200 with ETag v2; B sends PUT with If-Match v1 and gets 412 Precondition Failed, then re-reads, merges and tries again
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...UseRetry after a timeout?
Read a resourceGETYes
Run a read-only search with a big bodyQUERY where supported, else POSTYes for QUERY; for POST only if you document it as safe
Replace a resource whose URL the client knowsPUT (+ If-Match for edits)Yes
Create with a client-chosen IDPUT + If-None-Match: *Yes
Create in a collection, server picks the IDPOST + Idempotency-KeyOnly with the key
Change a few fieldsPATCH + If-MatchYes with If-Match, otherwise no
Trigger an action (send, charge, deploy)POST + Idempotency-KeyOnly with the key
Remove a resourceDELETEYes

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.

AE

Written by AIDToolStack Editorial

Researched from official documentation, specifications and vendor pages, listed under Sources below. Last checked November 2026.

Sources

  1. www.rfc-editor.org/rfc/rfc9110.html
  2. www.rfc-editor.org/rfc/rfc5789.html
  3. www.rfc-editor.org/rfc/rfc7396.html
  4. www.rfc-editor.org/rfc/rfc10008.html
  5. datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/
  6. datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/
  7. docs.stripe.com/api/idempotent_requests

Related Posts

Explore on AIDToolStack

Discover tools and servers featured in our directory.

MCP Servers

Trigger.dev Jobs MCP ServerManage Trigger.dev background jobs from your AI coding assistant. Monitor job runs, trigger tasks manually, inspect execution logs, manage schedules, and debug failed runs. The server provides operational visibility into your background job infrastructure — see which tasks are running, queued, or failed, and take action. Your AI can help diagnose job failures from execution logs, retry failed tasks, and optimize concurrency configurations for better throughput.Tailscale Network MCP ServerManage your Tailscale mesh VPN network from your AI coding assistant. View connected devices, manage ACLs, configure exit nodes, check device status, and manage DNS settings. The server provides visibility into your Tailscale network — see which machines are online, troubleshoot connectivity issues, manage network access policies, and configure routes. Useful for developers managing distributed infrastructure where Tailscale provides secure networking between services.Portainer Docker MCP ServerManage Docker environments through Portainer's API from your AI coding assistant. Control containers, images, networks, and volumes across multiple Docker hosts and Kubernetes clusters. The server provides tools for container lifecycle management, image pulling and building, stack deployment, and resource monitoring. Portainer's multi-environment management makes this server particularly valuable for teams managing containers across development, staging, and production environments.

Reviews

Sign in to leave a review.

No reviews yet. Be the first!

Comments

Sign in to leave a comment.

No comments yet. Be the first!

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.

Growing subscriber baseHigh open rates

All sponsored content is clearly labeled per our editorial policy.