Understanding HTTP 428 Precondition Required: Making If-Match Mandatory Without Breaking Your Clients
428 Precondition Required is the server's half of a deal that 412 Precondition Failed can't enforce alone. Conditional headers like If-Match are opt-in: a client that never sends one never gets a 412, and can overwrite other people's changes forever. 428 is how a server makes them mandatory. The usual mix-up is the order: 428 isn't a failed check, it means the client skipped the check entirely, so it comes before any 412. This post covers what 428 means, how it fits with 412 and 409, which writes should require a precondition, how to turn the requirement on without breaking existing clients, and how to return it in Express and Next.js.
What Is a 428?
A 428 means the origin server refused a request because the request wasn't conditional, and this server only accepts conditional requests for that operation.
The 428 status code indicates that the origin server requires the request to be conditional.
Its typical use is to avoid the "lost update" problem, where a client GETs a resource's state, modifies it, and PUTs it back to the server, when meanwhile a third party has modified the state on the server, leading to a conflict. By requiring requests to be conditional, the server can assure that clients are working with the correct copies. โ RFC 6585, Section 3
In plain English: "I won't let you change this unless you tell me which version you're changing." Nothing was written. The client should fetch the resource, note its ETag, and resend the write with that ETag in If-Match.
The same section adds two rules that matter in practice. Responses "SHOULD explain how to resubmit the request successfully", so a bare status line isn't enough. And a 428 response "MUST NOT be stored by a cache".
428 comes from RFC 6585 (2012), alongside 429, 431 and 511. The headers it asks for, If-Match, If-Unmodified-Since and friends, are defined in RFC 9110, Section 13.
428 Comes Before 412
Once a server requires preconditions, every write to a protected resource ends one of three ways:
- No precondition at all โ 428. The client never said which version it was editing.
- A precondition that's false, such as an
If-Matchwith an ETag that's no longer current โ 412. Someone else changed the resource first. - A precondition that's true โ the write goes ahead, typically with a 200 or 204 and a new
ETag.
Our 412 Precondition Failed post covers outcomes two and three: how ETags work, why If-Match needs strong comparison, and how to make the check and the write atomic. 428 adds the first outcome, and without it the other two are optional. A client that never sends If-Match never hits a 412, and its writes quietly overwrite everyone else's.
- 428 = "You didn't say only if." Add a precondition and try again.
- 412 = "You said only if, and it was false." Reload, reconcile, then try again.
RFC 6585's Security Considerations admit the limits: 428 "is optional; clients cannot rely upon its use to prevent 'lost update' conflicts." A client that wants protection should send If-Match on its own, whether or not the server insists.
Which Requests Should Require a Precondition?
Require If-Match where a stale write can destroy someone else's work, and nowhere else.
Good candidates:
PUTthat replaces a whole resource. The textbook lost update: the client sends back its entire copy, including fields it never touched.PATCHbuilt from a read-modify-write. If the patch was computed from what the client last saw (a list order, a total), a stale base corrupts the result.DELETEof something people edit. "Delete it only if it's still the version I looked at," so nobody deletes a document someone just rewrote.- Resources with several writers. Shared documents, settings, inventory counts: anything two people or jobs can edit at once.
Leave it off for:
GETandHEAD. Reads can't lose updates. Conditional reads are for caching and produce 304, never 428.POSTto a collection. A new order has no current version to match. Use an idempotency key for safe retries instead.- Single-writer or append-only data. If one process owns a record, or every write is a new row, there's nothing to overwrite.
For a client-chosen URL, the precondition flips: requiring If-None-Match: * on a create-only PUT means "create this only if nothing exists here", and a client that leaves it out gets a 428 rather than risking an overwrite.
API style guides disagree on whether to require preconditions at all. Finastra's Open API Design Guide makes it a rule: APIs that use optimistic locking must return 428 when a PUT arrives without If-Match, and 412 when it doesn't match. Google's AIP-154 defaults the other way: if the client sends no etag, the service should permit the request, and only services with strong consistency needs should reject it. Decide per resource, based on what a lost update would cost.
What counts as "conditional"?
RFC 6585 doesn't say which preconditions count. That's your call, so document it:
If-Matchwith a strong ETag is the one to require. RFC 9110, Section 13.1.1 requires exact, strong comparison for it.If-Unmodified-Sincerelies on dates. RFC 9110 notes that entity tags are more reliable "where the one-second resolution of HTTP-date values is not sufficient" (Section 8.8.3). Accept it only from clients that can't do ETags.If-Match: *only means "if the resource exists." It catches a delete, not a concurrent edit, so you can reasonably treat it as missing on updates. If you do, say so in the 428 body.
428 vs 412 vs 409 vs 400 vs 449
| Code | Meaning | Use when |
|---|---|---|
| 428 Precondition Required | A required conditional header is missing | A write to a protected resource arrives with no If-Match (or no If-None-Match: * on a create-only PUT) |
| 412 Precondition Failed | A conditional header evaluated false | The client sent If-Match, but the ETag isn't current |
| 409 Conflict | The request clashes with current state | Your application found the conflict itself, such as a stale version field in the body or a duplicate key |
| 400 Bad Request | The request is malformed | The syntax is broken, not just missing a header the server requires |
| 449 Retry With | IIS-specific: retry with more information | A Microsoft extension, not a standard code. Don't use it in a public API |
428 and 412 are a pair: missing precondition, failed precondition. If your API carries the version in the request body instead of headers, no HTTP precondition is involved, so a stale version is a 409 and a missing one is a 422 or 400. Our 409 Conflict post covers that style.
The Migration Problem
Requiring If-Match on a live API is a breaking change: every client that writes without it starts failing the moment you deploy. Older clients may not know 428 by name. RFC 9110, Section 15 says a client must "treat an unrecognized status code as being equivalent to the x00 status code of that class," so they see a generic 400 and probably give up. That's safe, since nothing was overwritten, but it's an outage for your users.
Roll it out in stages:
- Issue strong ETags first. Every
GETand successful write must return anETagbefore clients can send one back. For cross-origin browser clients, addETagtoAccess-Control-Expose-HeadersandIf-MatchtoAccess-Control-Allow-Headers, or they can't comply. - Run in shadow mode. Let unconditional writes through, but log each one with the client's identity (API key, user agent, app version). That's your list of who would break.
- Fix the clients you control. Update your SDKs, apps and frontends. Mobile apps take longest, because old versions stay installed long after you ship a fix.
- Enforce gradually. Turn on 428 for new API keys first, or one resource type, or a new API version. If you version the API, the Deprecation and Sunset headers on the old version tell clients it is deprecated and when it will stop working.
Flip the switch when the shadow-mode logs show no unconditional writes left, or only from clients you've decided to break.
Returning 428 Correctly
Authentication and authorization come first: an anonymous caller gets a 401 whether or not they sent If-Match. Ideally existence does too, so a missing resource is a 404. A 428 should mean "this would have worked with a precondition."
Express / Node.js
A small middleware handles both shadow mode and enforcement:
import type { NextFunction, Request, Response } from "express";
const PROTECTED_METHODS = new Set(["PUT", "PATCH", "DELETE"]);
export function requireIfMatch({ enforce }: { enforce: boolean }) {
return (req: Request, res: Response, next: NextFunction) => {
if (!PROTECTED_METHODS.has(req.method)) return next();
const ifMatch = req.get("If-Match")?.trim();
if (ifMatch && ifMatch !== "*") return next(); // the handler checks it (412 if stale)
if (!enforce) {
console.warn("unconditional write", {
method: req.method,
path: req.originalUrl,
client: req.get("User-Agent"),
});
return next();
}
res.set("Cache-Control", "no-store");
res.status(428).json({
error: "precondition_required",
message: "Updates must be conditional. GET the resource, then resend with If-Match set to its ETag.",
requiredHeader: "If-Match",
});
};
}Mount it after authentication, so anonymous callers still get a 401:
app.use(
"/api/articles",
authenticate,
requireIfMatch({ enforce: process.env.REQUIRE_IF_MATCH === "true" }),
articlesRouter,
);Because it runs before the article is loaded, a bare PUT to a missing article gets a 428, not a 404. If existence should win, check inside the handler after the lookup, as the 412 post's Express example does. Either way, the handler still compares the ETag and returns the 412.
Next.js App Router
In a route handler, check for the header after the lookup and before touching the body:
// app/api/articles/[id]/route.ts
export async function PATCH(
request: Request,
{ params }: { params: Promise<{ id: string }> },
) {
const { id } = await params;
const article = await getArticle(id);
if (!article) {
return Response.json({ error: "not_found" }, { status: 404 });
}
const ifMatch = request.headers.get("if-match")?.trim();
if (!ifMatch || ifMatch === "*") {
return Response.json(
{
error: "precondition_required",
message: "Send If-Match with the ETag from your last GET of this article.",
requiredHeader: "If-Match",
},
{ status: 428, headers: { "Cache-Control": "no-store" } },
);
}
// From here it's the 412 flow: compare ifMatch inside the write,
// return 412 with the current ETag if it's stale.
return updateWithPrecondition(article, ifMatch, await request.json());
}In Next.js 15 and later, route handler params is a Promise, so await it before reading id.
REST API JSON body
HTTP/1.1 428 Precondition Required
Content-Type: application/json
Cache-Control: no-store
{
"error": "precondition_required",
"message": "This resource requires conditional updates. GET it, then resend your request with If-Match set to the ETag you received.",
"requiredHeader": "If-Match",
"docs": "https://example.com/docs/concurrency"
}Notice what's missing: the current ETag. It looks helpful, but a lazy client will copy it into If-Match and resend its old body, a blind overwrite with extra steps. Make the client GET the resource and see what's there before it writes.
Handling 428 on the Client
A 428 almost always means a client bug, one that should show up once in development and never again. Pair every write with the read it's based on: GET the resource, keep its ETag, and send it in If-Match on the PUT, PATCH or DELETE. If the ETag is null in the browser, the server hasn't listed it in Access-Control-Expose-Headers. And if the write then returns 412, follow the reconcile flow from the 412 post instead of retrying.
428 and SEO
Crawlers don't PUT or PATCH, so a correctly scoped requirement never reaches them. The risk is scoping it too broadly: middleware that demands If-Match on every method, GET included, turns public pages into 428s. Google says it doesn't index URLs that return a 4xx status code (other than 429), and removes ones already indexed. Keep the requirement to unsafe methods on API routes, and spot-check public URLs with curl -I after rolling it out.
Common Pitfalls
- Requiring preconditions on reads. It breaks browsers, caches and crawlers, and reads can't lose updates anyway.
- Returning 412 when the header is missing. 412 means a precondition was sent and failed. A missing one is a 428, and mixing them up hides the real fix.
- Flipping it on for everyone at once. Ship strong ETags first, use shadow-mode logs to find who would break, then enforce gradually.
- A bare 428 with no body. RFC 6585 says the response should explain how to resubmit. Name the header and where its value comes from.
- Handing out the ETag in the 428. Clients will echo it back without reloading. Make them
GETfirst. - Letting caches store it. RFC 6585 says a 428 must not be stored by a cache. Send
Cache-Control: no-store.
Wrapping Up
428 is how a server makes lost-update protection mandatory instead of optional. The rules of thumb:
- 428 means the request should have been conditional and wasn't. Nothing was changed
- 428 for a missing precondition, 412 for a failed one, 409 for conflicts your application finds in the request body
- Require
If-MatchonPUT,PATCHandDELETEof shared, editable resources, never onGET - Turning it on is a breaking change: issue ETags first, log in shadow mode, then enforce gradually
- Explain how to resubmit, send
Cache-Control: no-store, and leave the current ETag out - 428 is optional for servers, so careful clients send
If-Matchwhether or not it's required
For more, see our pages on 428 Precondition Required, 412 Precondition Failed and 409 Conflict. ETags, If-Match and the atomic check-and-write are in understanding 412 Precondition Failed, body-based optimistic locking is in understanding 409 Conflict, and you can compare 412 vs 428 side by side.
Related Status Codes
- 400Bad Request
- 401Unauthorized
- 402Payment Required
- 403Forbidden
- 404Not Found
- 405Method Not Allowed
- 406Not Acceptable
- 407Proxy Authentication Required
- 408Request Timeout
- 409Conflict
- 410Gone
- 411Length Required
- 412Precondition Failed
- 413Payload Too Large
- 414URI Too Long
- 415Unsupported Media Type
- 416Range Not Satisfiable
- 417Expectation Failed
- 418I'm a Teapot
- 421Misdirected Request
- 422Unprocessable Entity
- 423Locked
- 424Failed Dependency
- 425Too Early
- 426Upgrade Required
- 428Precondition Required
- 429Too Many Requests
- 431Request Header Fields Too Large
- 451Unavailable For Legal Reasons