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

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

bash
curl -si https://api.example.com/orders/1001 | grep -i '^etag'
# ETag: "v12"

Then send the write with that value, including the double quotes:

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

js
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-Match is not a substitute for If-Match on updates. Some APIs accept If-Unmodified-Since instead; others take only If-Match.
  • No ETag to send. If the GET response has no ETag, look for a version in the JSON body or a Last-Modified header, 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.

python
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 resp

A few practical points:

  • Always return the current ETag on 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-Match uses strong comparison, so weak ones (W/"v12") never match.
  • Make sure your CDN and proxies pass ETag and If-Match through 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-Match value that can't be parsed. See 400 Bad Request.

Don't retry a 428 unchanged

A 428 will not fix itself. Retrying the identical request, with backoff or without, just repeats the refusal. Change the request by adding the condition.

Checking what an endpoint returns

To see whether a resource exposes an ETag and what else comes back, look at the raw response headers.

HTTP headers checkerSee the status code and every response header, including ETag and Cache-Control, for any URL.

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.

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

Keep reading