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

431 Request Header Fields Too Large: causes and fixes

Meaning

431 means the server refused your request because its headers are too big, in total or in one field such as Cookie. Trim them before resending.

When a proxy returns 431

The request line and headers you sent were bigger than the server was willing to read, so it refused the request before looking at the URL. RFC 6585 section 5 defines “431 Request Header Fields Too Large” for a server “unwilling to process the request because its header fields are too large”. The code covers a large total and a single oversized field, and in the second case the response SHOULD say which field it was. The RFC also says the request MAY be resubmitted after the headers are reduced. Sending the same headers again gets the same answer.

Cookie is the usual culprit. A long-running session collects cookies from every response, and the whole cookie jar for the host goes out on every request. Large bearer tokens and long Referer values come next.

The ceiling is different on every server

We grew a single Cookie header against five servers with default settings, using raw sockets so every byte was counted, and bisected to the exact size where 200 turned into a refusal. Both full runs gave identical byte counts. “Largest request accepted” counts the request line, every header line and the closing blank line.

Largest request accepted before the first refusal, default settings, measured by bisection Drawn from the table below.
Largest request accepted before the first refusal, default settings, measured by bisection. Bar chart of Largest request accepted by Server (defaults).5 rows, drawn from the table that follows this chart.Apache httpd 2.4.67Apache httpd 2.4.67: 8,253 bytes8,253 bytesNode.js 24.2.0Node.js 24.2.0: 16,412 bytes16,412 bytesSquid 6.13, as a forward proxySquid 6.13, as a forward proxy: 65,535 bytes65,535 bytesPython 3.15.0 http.serverPython 3.15.0 http.server: 65,596 bytes65,596 bytesGo 1.24.4 net/httpGo 1.24.4 net/http: 1,052,672 bytes1,052,672 bytes0500K1M1.5M bytesLargest request accepted before the first refusal, default settings, measured by bisection. Bar chart of Largest request accepted by Server (defaults).5 rows, drawn from the table that follows this chart.Apache httpd 2.4.67Apache httpd 2.4.67: 8,253 bytes8,253 bytesNode.js 24.2.0Node.js 24.2.0: 16,412 bytes16,412 bytesSquid 6.13, as a forwardproxySquid 6.13, as a forward proxy: 65,535 bytes65,535 bytesPython 3.15.0http.serverPython 3.15.0 http.server: 65,596 bytes65,596 bytesGo 1.24.4 net/httpGo 1.24.4 net/http: 1,052,672 bytes1,052,672 bytes0500K1M1.5M bytes
Server (defaults) Largest request accepted First refusal
Apache httpd 2.4.67 8,253 bytes 400 Bad Request
Node.js 24.2.0 16,412 bytes 431 Request Header Fields Too Large
Squid 6.13, as a forward proxy 65,535 bytes 431 Request Header Fields Too Large
Python 3.15.0 http.server 65,596 bytes 431 Line too long
Go 1.24.4 net/http 1,052,672 bytes 431 Request Header Fields Too Large

Three details matter more than the numbers. Apache does not send 431 at all: it answers 400 with “Size of a request header field exceeds server limit”, and nginx does the same through its internal 494 code, whose page is titled “400 Request Header Or Cookie Too Large”. A client that only checks for 431 misses both. Python puts its own message in the status line, so the reason phrase reads “Line too long”, and a 101st header line produces “431 Too many headers” regardless of size. Go’s ceiling sat exactly 4,096 bytes above its DefaultMaxHeaderBytes of 1,048,576.

Reproduce it with curl

An unmodified Node.js server is enough, since its documented default is 16 KiB:

// node431.mjs, Node.js 24.2.0, no options changed
import http from 'node:http';
http.createServer((req, res) => res.end('ok\n')).listen(37431, '127.0.0.1');

A 20,000-character cookie pushes curl 8.23.0 over it. The long Cookie line is left out of the paste:

$ python3 -c "print('Cookie: a='+'x'*20000)" > cookie20k.txt
$ curl -sv -H @cookie20k.txt http://127.0.0.1:37431/
*   Trying 127.0.0.1:37431...
* Established connection to 127.0.0.1 (127.0.0.1 port 37431) from 127.0.0.1 port 57081
* using HTTP/1.x
> GET / HTTP/1.1
> Host: 127.0.0.1:37431
> User-Agent: curl/8.23.0
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 431 Request Header Fields Too Large
< Connection: close
<
{ [0 bytes data]
* shutting down connection #0

Node’s 431 has no body, so it does not say which header was too big. To find the fat one yourself, measure what your client is about to send. This uses Python 3.9.6 with requests 2.32.3 against the same server:

import requests

URL = "http://127.0.0.1:37431/"

s = requests.Session()
for i in range(40):                       # a session that picked up 40 tracking cookies
    s.cookies.set(f"_trk{i}", "v" * 400, domain="127.0.0.1", path="/")

def header_sizes(session, url):
    req = session.prepare_request(requests.Request("GET", url))
    return {k: len(k) + 2 + len(v) + 2 for k, v in req.headers.items()}   # "Name: value\r\n"

sizes = header_sizes(s, URL)
for name, n in sorted(sizes.items(), key=lambda kv: -kv[1]):
    print(f"{n:>6}  {name}")
print("status:", s.get(URL).status_code)

for c in [c for c in s.cookies if c.name.startswith("_trk")]:
    s.cookies.clear(c.domain, c.path, c.name)   # drop what the target does not need
print("after trim:", sum(header_sizes(s, URL).values()), "bytes, status:", s.get(URL).status_code)
 16358  Cookie
    42  Accept-Encoding
    36  User-Agent
    24  Connection
    13  Accept
status: 431
after trim: 115 bytes, status: 200

The prepared request does not include Host yet, which is added at send time. For what other clients put in their headers by default, see What HTTP clients send before you configure anything.

When a proxy returns 431

Look at who signed the response. Squid 6.13 refusing a request itself, at its documented 64 KB request_header_max_size, sent Server: squid/6.13 and X-Squid-Error: ERR_TOO_BIG 0. When Squid forwarded a 20 KB cookie to the Node server and relayed Node’s refusal, the 431 had no Server header from Squid and gained Via: 1.1 proxy-host (squid/6.13) (hostname masked).

Proxies also make requests bigger on the way through. A curl request that reached our capture server as 79 bytes direct arrived as 206 bytes through Squid with default settings, which added Via, X-Forwarded-For, Cache-Control and Connection. The exact growth depends on the proxy’s hostname in Via. One hop rarely matters on its own, but a request already close to a total limit, such as Node’s 16 KiB, can cross it after a chain of them.

For scrapers, the fix is usually cookie hygiene. If you rotate the exit IP, rotate the cookie jar with it, as Rotating vs sticky sessions explains; replaying one growing jar from many addresses also looks odd to the target.

Causes and fixes

Cause How to confirm it What to change
Cookie jar grew during a long session Cookie is the largest header in the size dump, and grows over time Clear the jar when you change identity; drop cookies the target does not need
Cookies from other apps on localhost Fails only in local development; works in a private window Clear localhost cookies, or start Node with --max-http-header-size=32768
Oversized Authorization or custom header That header tops the size dump Send a shorter token, or move data into the body where the API allows
Headers added along a proxy chain Compare the request size at the origin direct and through the proxy Fewer hops; on a Squid you run, via off and forwarded_for delete
A strict server limit 400 rather than 431 at around 8 KB in a single field On your own server, raise LimitRequestFieldSize or large_client_header_buffers

The localhost case catches developers because cookies ignore ports. RFC 6265 states it plainly: “Cookies do not provide isolation by port.” Every app you have run on localhost adds to the same jar.