428 Precondition Required: why the API wants If-Match and how to send it
A 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.
· 6 min read · By the Spot Downtime team
A 428 Precondition Required response means the server will only accept this request if it is conditional, and yours wasn't. You sent a PUT, PATCH or DELETE without an If-Match (or similar) header, and the API refuses to guess. It is defined in RFC 6585 and exists to prevent the lost update problem: a client reads a resource, someone else changes it, and the client then overwrites that change without ever knowing.
The fix is almost always on the client: read the resource first, take its ETag, and send it back in If-Match. This post shows how, and what to do with the answers you get afterwards.
What a 428 looks like
PATCH /orders/1001 HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"status": "shipped"}
HTTP/1.1 428 Precondition Required
Content-Type: application/json
{"error": "This request must be conditional. Send If-Match."}The response body is usually a hint. RFC 6585 says the response should explain what is required, but it doesn't mandate a format, so read the body and the API docs.
Fix it: read, then write with If-Match
First fetch the resource and note its validator:
curl -si https://api.example.com/orders/1001 | grep -i '^etag'
# ETag: "v12"Then send the write with that value, including the double quotes:
curl -i -X PATCH https://api.example.com/orders/1001 \
-H 'If-Match: "v12"' \
-H 'Content-Type: application/json' \
-d '{"status":"shipped"}'In JavaScript the same flow looks like this:
const read = await fetch("https://api.example.com/orders/1001");
const etag = read.headers.get("ETag"); // keep the quotes as received
const order = await read.json();
const res = await fetch("https://api.example.com/orders/1001", {
method: "PATCH",
headers: { "If-Match": etag, "Content-Type": "application/json" },
body: JSON.stringify({ ...order, status: "shipped" }),
});If the API uses a different mechanism, for example a version field in the body, its docs will say so. The 428 response normally names the header it needs.
What happens after you send the condition
- 2xx. The ETag matched and the write was applied. Store the new ETag from the response if the server returns one.
- 412 Precondition Failed. Someone changed the resource since you read it. Re-read, merge or ask the user, and retry with the new ETag. See 412 Precondition Failed.
- 428 again. The header was ignored or stripped. Check for a proxy that removes it, a client library that doesn't forward custom headers on that method, or a header name typo.
When it still returns 428
- Wrong header.
If-None-Matchis not a substitute forIf-Matchon updates. Some APIs acceptIf-Unmodified-Sinceinstead; others take onlyIf-Match. - No ETag to send. If the GET response has no
ETag, look for a version in the JSON body or aLast-Modifiedheader, as documented by the API. - Header dropped in transit. Compare what your client sends with what arrives. A request bin or the webhook tester shows the headers a receiver actually gets.
- SDK wrappers. Some generated clients have a separate parameter for the precondition. Reading the raw request in debug logs shows whether it was added.
Server side: when to return 428
If you run the API, 428 is a deliberate design choice. Require conditional writes on resources where a silent overwrite would hurt: documents, settings, inventory counts, anything several people or services edit.
from flask import request, jsonify
@app.patch("/orders/<int:order_id>")
def update_order(order_id):
if "If-Match" not in request.headers:
return jsonify(error="If-Match header required"), 428
order = load_order(order_id)
if request.headers["If-Match"] != etag_for(order):
return jsonify(error="resource changed", current_etag=etag_for(order)), 412
apply_changes(order, request.get_json())
resp = jsonify(order.to_dict())
resp.headers["ETag"] = etag_for(order)
return respA few practical points:
- Always return the current
ETagon reads and on successful writes, so clients don't need an extra GET. - Put a clear message in the 428 body saying which header to send. A bare 428 sends developers to your support inbox.
- Use strong ETags.
If-Matchuses strong comparison, so weak ones (W/"v12") never match. - Make sure your CDN and proxies pass
ETagandIf-Matchthrough unchanged.
428 compared with 409, 412 and 400
- 428: the request had no precondition and the server requires one.
- 412: the request had a precondition and it was false.
- 409: the server found a conflict on its own, such as a duplicate or invalid state. See 409 Conflict.
- 400: the request was malformed, for example an
If-Matchvalue that can't be parsed. See 400 Bad Request.
Don't retry a 428 unchanged
Checking what an endpoint returns
To see whether a resource exposes an ETag and what else comes back, look at the raw response headers.
Monitoring conditional write flows
A plain GET check never exercises a write, so it won't notice if a deploy starts rejecting conditional requests. An API monitor can run a sequence: read the resource, capture the ETag, send the conditional write and assert on the status. 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 · APIs412 Precondition Failed: If-Match, ETags and lost updatesA 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.November 14, 2026 · 7 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