The GET Worked. Why Did My If-Match Update Return 412?

A 412 can mean another editor saved first, or that your ETag never matched the write endpoint. A two-editor test tells you where to look.

Share
Two orange document plates sit in front of a dark gate, with the offset plate stopped by a latch.

The GET comes back 200 OK with an ETag. Your editor sends it straight back in If-Match. The save still gets 412 Precondition Failed. Before you add a retry, check whether the tag is strong and whether the read and write endpoints agree on what it validates. A 412 can mean somebody edited the record first. It can also mean the client brought a perfectly good tag to the wrong comparison.

The first useful test is a fresh read and conditional write against the same resource and documented representation in a quiet test environment. If that works and the old tag fails after a second editor changes the record, the guard is doing its job. If a fresh tag fails every time, follow it through the request before blaming concurrent editors. Whatever you do, don't take If-Match out to make the error disappear. You'd be turning a visible conflict into a possible silent overwrite.

This is an AI-prepared, documentation-based explainer, not a personally reproduced incident. The walkthrough and HTTP examples are illustrative and were not run against an API. See the editorial policy.

What did that GET actually prove?

It proved the server could serve a representation. It didn't prove that the tag was suitable for a conditional write. An ETag is an opaque validator for a representation: don't parse a revision out of it or reconstruct it from the body. A tag that starts with W/ is weak. Under the strong comparison rules in RFC 9110, two tags match only if neither is weak and their opaque values are identical. W/"rev-17" doesn't match even another W/"rev-17" for If-Match. Removing W/ is editing the label, not changing what the server promised.

A weak tag can still be useful for cache revalidation, which explains why the same header value looks fine in a network trace from a read-heavy part of the app. That's a different question from “can I apply this edit to the version I saw?” The If-Match rule requires a strong comparison against the selected representation. When the condition is false, the server must not perform the method; it normally responds with 412. There is a narrow allowance to return success when the server can determine that the requested change already succeeded. A client shouldn't count on that allowance as a retry strategy.

Try two reads, two writes, and one deliberate conflict

Use a disposable record in a test environment. Say two editors read the same settings resource and both receive "rev-17". These numbers are just labels for the example; real tags don't have to look like this. Have the first editor change a setting with If-Match: "rev-17". After that succeeds, read again and confirm the current tag changed. Now have the second editor submit a different change with the original tag. Expect a 412 and verify that the first change survived. Then re-read, show or reconcile the differences, and submit only the intended edit against the new tag. An automatic retry that replaces the header but keeps the old full document can still erase the other editor's work.

Suppose the first write fails instead, even on an isolated record. Now you've got a smaller problem to investigate:

  1. Check the value on the wire. Preserve the quotes in the header and look for a W/ prefix. Verify what the write handler actually receives; client and origin traces can separate header loss from a failed comparison. Avoid sharing authorization headers or private response bodies in bug reports.
  2. Compare what you read and what you're writing. A collection's tag doesn't validate one member. A GET from a different API version or a negotiated representation may not provide the tag the write contract expects. For example, RFC 9110 distinguishes strong tags for encoded and unencoded variants. Compare the documented read and write pair on the same resource, and record Vary, Content-Encoding and any intermediary involved. Don't assume a different tag proves another user saved something.
  3. Check for a stale read before calling it a server bug. Ask for revalidation with Cache-Control: no-cache if caching is in play, or use a supported route that reads current state. That request directive doesn't bypass every server-side cache or replica. If the same strong tag still fails on a known-current read in an isolated environment, compare the validator issued by the read handler with the one checked by the write handler. At this point “try again” has had a fair audition.

The header can travel with a PATCH where the API supports it. For example, in an illustrative API that documents JSON Patch and publishes a usable strong tag, the relevant part of the request could look like this (other headers omitted):

PATCH /settings/42 HTTP/1.1
If-Match: "rev-17"
Content-Type: application/json-patch+json

[{"op":"replace","path":"/emailDigest","value":false}]

RFC 5789 recommends a conditional PATCH with a strong ETag when the patch format depends on a known base. Your API still has to support the method, the patch format, and the validator contract. A smaller patch limits what you intend to touch; it doesn't make competing edits safe by itself. And If-Match: * tests whether a current representation exists, not whether it's the one you read.

Make the API prove it can reject a stale edit

If you own the API, test both sides of the contract. A fresh GET token should allow the documented write in isolation; after a successful intervening edit, the stale token should fail and leave state unchanged. Enforce the compare and write together at the storage boundary, so two requests can't both pass a check and then overwrite each other. If the API requires a precondition but none was sent, 428 Precondition Required describes that case; it isn't the same as rejecting a precondition that was sent.

For the cache side of the investigation, see which cache header wins. For an editor, keep the two-client test close to the endpoint contract: it should fail if a stale edit slips through or if a fresh edit is rejected. A system that always says no hasn't solved the problem either.