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 GMT means "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-Match and If-Modified-Since on a GET are different: they produce 304 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.

http
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:

bash
# 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.

js
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-Match requires strong comparison, so a weak ETag never matches, even to itself. Servers and frameworks that only produce weak ETags will return 412 for every If-Match write.
  • 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-cache before 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:

python
# 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-Match or If-Unmodified-Since on 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 own Last-Modified header, 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-Match or If-Modified-Since. It is a success path, not an error.

Don't turn a 412 into a force-overwrite

The tempting fix for an annoying 412 is to drop the 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.

HTTP headers checkerSee the status code and every response header, including ETag, that a URL returns from outside your network.

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.

Unsubscribe from any email with one click. See our privacy policy.

Keep reading