Precondition Failed

4xx · Client Error

Overview

412 Precondition Failed means a condition in the request headers (If-Match, If-Unmodified-Since, etc.) evaluated to false on the server, so the request was not performed. It most commonly arises in optimistic concurrency control when someone else modified the resource first.

If the client sends a previously fetched ETag via If-Match but the resource has since changed and its current ETag differs, the server returns 412 to prevent overwriting. This guards against the lost-update problem.

When it happens

The ETag sent in If-Match no longer matches the server's current ETag
The resource was actually modified after the If-Unmodified-Since timestamp
Multiple clients try to edit the same resource concurrently

Request / Response example

Request

PUT /docs/42 HTTP/1.1
Host: api.example.com
If-Match: "a1b2c3"
Content-Type: application/json

{"title":"Updated"}

Response

HTTP/1.1 412 Precondition Failed
Content-Type: application/json

{"error":"etag_mismatch","current":"\"z9y8x7\""}

In code

app.put('/docs/:id', (req, res) => {
  const doc = db.get(req.params.id);
  if (req.headers['if-match'] !== doc.etag) {
    return res.status(412).json({ error: 'etag_mismatch', current: doc.etag });
  }
  db.update(req.params.id, req.body);
  res.json({ ok: true });
});

curl -X PUT https://api.example.com/docs/42 \
  -H 'If-Match: "a1b2c3"' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Updated"}'

Common causes

Another request changed the resource after you fetched it (ETag mismatch)
A stale If-Match / If-Unmodified-Since value was used
A cached ETag was reused without refreshing

How to fix

Re-fetch the resource to get the current ETag, merge your changes, and retry
Remove precondition headers like If-Match if the conditional check is not actually needed
Surface the conflict to the user so they can choose which change wins

Notes

For safe reads (GET) a true condition yields 304 Not Modified, while for writes (PUT/PATCH/DELETE) a false condition yields 412.
If the server wants to require a conditional request but the client sent no precondition at all, use 428 Precondition Required instead of 412.