Skip to content
4284xx · Client errorThe client seems to have erred. RFC 9110 §15.5

HTTP 428 Precondition Required: meaning and fixes

Meaning

HTTP 428 Precondition Required means a write must include a condition such as If-Match. Fetch the current ETag before retrying.

HTTP 428 means the origin requires a conditional request: “Precondition Required”. RFC 6585 section 3 defines it for resources that want clients to use a precondition such as If-Match before a write. The purpose is to prevent a client from overwriting a newer representation it never read.

428 is different from 412. A 428 says the required condition was missing. A 412 says a condition was supplied but evaluated false. A proxy can relay either response, but the condition belongs to the origin resource and should survive a change of proxy address.

Reproduce an ETag precondition

This Python 3.15.0 server keeps a document and changes its ETag after each successful PUT:

import hashlib
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

doc = {"body": b'{"title": "draft one"}\n'}
def etag():
    return '"' + hashlib.sha256(doc["body"]).hexdigest()[:12] + '"'

class H(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"
    def reply(self, code, body=b"", extra=()):
        self.send_response(code)
        for key, value in extra:
            self.send_header(key, value)
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)
    def do_GET(self):
        self.reply(200, doc["body"], [("ETag", etag())])
    def do_PUT(self):
        new = self.rfile.read(int(self.headers.get("Content-Length", 0)))
        sent = self.headers.get("If-Match")
        if sent is None:
            return self.reply(428, b'This request is required to be conditional; try using "If-Match".\n')
        if sent != etag():
            return self.reply(412, b"ETag has changed; GET the resource again.\n")
        doc["body"] = new
        self.reply(204, extra=[("ETag", etag())])

ThreadingHTTPServer(("127.0.0.1", 47428), H).serve_forever()
$ curl -si -X PUT --data '{"title":"draft two"}' http://127.0.0.1:47428/doc
HTTP/1.1 428 Precondition Required
Server: BaseHTTP Python/3.15.0
Content-Type: text/plain
Content-Length: 66

This request is required to be conditional; try using "If-Match".

$ ETAG=$(curl -s -o /dev/null -w "%header{etag}" http://127.0.0.1:47428/doc)
$ curl -s -o /dev/null -w "%{http_code} new etag %{header{etag}}\n" -X PUT -H "If-Match: $ETAG" --data '{"title":"draft two"}' http://127.0.0.1:47428/doc
204 new etag "bbd9956b020a"

$ curl -s -w "%{http_code}\n" -X PUT -H "If-Match: $ETAG" --data '{"title":"draft three"}' http://127.0.0.1:47428/doc
412

The capture used curl 8.7.1 and the standard library. The second write used a current tag and succeeded; reusing that old tag produced 412. Through Squid 6.13, the same request without If-Match returned 428 and a fresh conditional request returned 204. The proxy did not create the precondition.

What to change in a client

GET the representation, save its ETag, apply your change locally and send If-Match: "tag" with the write. If the server returns 412, GET again and merge the newer representation. An If-None-Match header has different semantics and can be wrong for an update. curl’s --etag-compare option is designed for cache validation, not for inventing an If-Match update token.

A scraper normally sees 428 only when it is writing or calling an API that requires an idempotency or version header. A proxy that strips conditional headers can turn a valid request into 428, so compare the headers at the origin when you control the path. Do not send a stale tag forever or rotate addresses to escape the conflict.

For a write that may be retried after a timeout, combine If-Match with an idempotency key if the API documents one. A conditional request prevents an old representation from overwriting new data, but it cannot tell you whether a timed-out write was already committed.

Causes and fixes

Cause Response Fix
PUT or PATCH has no precondition 428 and a body names If-Match or another condition GET the resource and send the required header
ETag is stale 412 after a conditional write Fetch the current representation, merge and retry once
Wrong conditional header 428 persists after using If-None-Match on an update Follow the API contract and use the header it requires
Proxy strips the condition Direct write succeeds, proxied write gets 428 Inspect proxy header policy and preserve If-Match
Client copied an ETag from another URL 412 on every write to the target Read the target’s own ETag before the write

See HTTP 412 for failed conditions and Retry-After for a different kind of retry signal. The curl proxy guide shows how to compare direct and proxied conditional headers. A 428 is a request-shape problem, not a proxy reputation signal.

A custom API may also require an idempotency key, but that is application policy rather than a standard HTTP precondition. Treat the response body and API documentation as the authority, preserve the conditional header through every proxy hop, and fetch a fresh representation after a 412.

Frequently asked questions

What does 428 require?
The resource API decides which precondition is required. Common choices are If-Match, If-Unmodified-Since or an idempotency header.
Why did my retry change to 412?
The first request lacked a condition and got 428. An old ETag then evaluated as false and returned 412.

Sources

  1. RFC 6585 section 3: 428 Precondition Required
  2. RFC 9110 section 13.1.1: If-Match

All terms, A to Z