412 Precondition Failed: If-Match, ETags and lost updates
A 412 means a conditional header such as If-Match or If-Unmodified-Since didn't hold. Why it happens, how to fix it in clients and servers, and how it differs from 409.
· 7 min read · By the Spot Downtime team
A 412 Precondition Failed response means the request included a condition, usually in an If-Match or If-Unmodified-Since header, and the server checked it and found it false. The server did not perform the action. The status exists to stop two clients from silently overwriting each other's changes, so in most cases a 412 is the system working as designed. It becomes a problem when clients handle it badly, or when a proxy or CDN rewrites the validators and the condition can never match.
How conditional requests work
A server that supports conditional requests gives each resource a validator: an ETag (an opaque version string) or a Last-Modified date. The client sends the validator back in a precondition header, and the server only proceeds if the condition holds.
If-Match: "v7"means "do this only if the current ETag is v7". A mismatch gives 412.If-Unmodified-Since: Sat, 14 Nov 2026 09:00:00 GMTmeans "do this only if nothing changed after that time". If it did change, 412.If-None-Match: *on a PUT means "create this only if it doesn't exist yet". If it exists, 412.If-None-MatchandIf-Modified-Sinceon a GET are different: they produce304 Not Modified, not 412.
The typical flow is optimistic concurrency. Client A and client B both read a document with ETag "v7". A saves first and the ETag becomes "v8". When B saves with If-Match: "v7", the server answers 412 instead of overwriting A's work.
PUT /documents/42 HTTP/1.1
Host: api.example.com
If-Match: "v7"
Content-Type: application/json
{"title": "Quarterly report"}
HTTP/1.1 412 Precondition Failed
ETag: "v8"
Content-Type: application/json
{"error": "document changed since you read it"}Reproduce it with curl
Fetch the resource, note its ETag, then send a write with a deliberately stale one:
# Read the current ETag
curl -sI https://api.example.com/documents/42 | grep -i etag
# Write with a stale ETag - expect 412
curl -i -X PUT https://api.example.com/documents/42 \
-H 'If-Match: "stale-value"' \
-H 'Content-Type: application/json' \
-d '{"title":"Quarterly report"}'If a write with the correct, current ETag also returns 412, the problem is not concurrency. Look at the causes below.
Cause 1: someone really did change it first
This is the normal case. The resource changed between the client's read and its write. The right response is not to retry the same request. Re-read the resource, merge or ask the user, and send the write again with the new ETag.
async function saveDocument(id, edit) {
for (let attempt = 0; attempt < 3; attempt++) {
const res = await fetch(`/api/documents/${id}`);
const etag = res.headers.get("ETag");
const current = await res.json();
const put = await fetch(`/api/documents/${id}`, {
method: "PUT",
headers: { "If-Match": etag, "Content-Type": "application/json" },
body: JSON.stringify(edit(current)),
});
if (put.status !== 412) return put;
// 412: someone else saved first. Loop re-reads and re-applies the edit.
}
throw new Error("Could not save: the document keeps changing");
}Cap the retries. If an edit can't be re-applied automatically, surface the conflict to the user instead of looping.
Cause 2: the ETag the client sends is not the one the server has
If nobody else edited the resource and you still get 412, the validator is being altered or mismatched. Common reasons:
- Weak versus strong ETags. A weak ETag looks like
W/"v7".If-Matchrequires strong comparison, so a weak ETag never matches, even to itself. Servers and frameworks that only produce weak ETags will return 412 for everyIf-Matchwrite. - Compression changing the ETag. Some servers and CDNs modify the ETag when they gzip a response, for example nginx turning a strong ETag weak when it compresses on the fly. The client then stores a value the origin doesn't recognise.
- Quotes dropped. ETags include their double quotes. Stripping them in client code, or sending
If-Match: v7, fails the match on strict servers. - Different servers computing different ETags. With Apache, ETags that include the inode number differ between servers behind a load balancer. A client reads from one and writes to another and gets 412.
- Stale cached read. The client took its ETag from a cached copy. Re-fetch with
Cache-Control: no-cachebefore computing the next write.
Compare the ETag in the read response, the one the client sends, and the one on a fresh read straight from the origin. Whichever step changes the value is the culprit.
Fixing ETags on the server
For nginx behind a load balancer, give every node the same ETag by basing it on content or a version column rather than a file's inode or time. For application-level resources, use a version number or a hash of the content:
# Flask-style example: strong ETag from a row version
import hashlib
def etag_for(doc):
return '"%s"' % hashlib.sha256(f"{doc.id}:{doc.version}".encode()).hexdigest()[:16]Cause 3: a precondition the client didn't mean to send
If-None-Match: *on a PUT used as "create only" fails with 412 on the second attempt. If a client retries after a timeout and the first request actually succeeded, the retry returns 412. Treat that as a likely success and check the resource.- Some object storage and file APIs accept
If-MatchorIf-Unmodified-Sinceon writes, deletes and copy operations, and answer 412 when the object has changed. SDK upload helpers sometimes add these automatically. - Clock skew with
If-Unmodified-Since: the date must come from the server's ownLast-Modifiedheader, not from the client's clock.
412 versus 409, 428 and 304
- 409 Conflict is for a conflict the server detects on its own, such as a duplicate record or an invalid state transition. 412 is for a condition the client explicitly sent. See 409 Conflict.
- 428 Precondition Required means the server insists on a conditional header and you didn't send one. APIs use it to force clients into optimistic concurrency. Add
If-Match. - 304 Not Modified is the "condition failed" answer for GET and HEAD with
If-None-MatchorIf-Modified-Since. It is a success path, not an error.
Don't turn a 412 into a force-overwrite
If-Match header. That removes the protection, and a later write will silently destroy someone else's changes. Fix the validator mismatch instead.Inspecting the headers a URL returns
Most 412 debugging comes down to seeing exactly which ETag, Last-Modified and Cache-Control headers come back, and whether they change between requests.
Monitoring for it
A 412 only appears on writes, so a simple page check will never see it. If an API you depend on or provide uses conditional writes, an API monitor that reads a resource, extracts its ETag and sends a conditional write can confirm that the flow still works after a deploy or CDN change. Multi-step API checks are built for that kind of sequence; see how to set up multi-step API checks.
Get new guides by email
Practical posts on monitoring, outages, error fixes and on-call, when they're published. No spam.
Keep reading
- HTTP errors · APIs428 Precondition Required: why the API wants If-Match and how to send itA 428 means the server refuses unconditional writes and requires headers like If-Match. How to read the ETag, send the condition and handle 412 in your client.November 15, 2026 · 6 min read
- HTTP errors · APIs411 Length Required: what it means and how to fix itA 411 means the server wants a Content-Length header and the request did not have one. Why it happens with curl, chunked uploads and proxies, and the fixes.November 10, 2026 · 5 min read