431 Request Header Fields Too Large

The 431 status code indicates that the server is unwilling to process the request because there are too many headers to process, or one of the headers is too long to process.

Most HTTP requests by a Web browser will not contain more than a dozen headers, and will be less than a few hundred characters each. Servers will typically not accept more than a hundred headers, or a thousand characters on a line, because there is typically no affect on the response, and it only serves to negatively impact performance. So to prevent excessive resource usage, servers may reject these requests entirely.

Writing responses (servers)

Servers produce this status code when the server would have to consume an excessive amount of resources buffering the request headers. This can be triggered in two cases:

Parsing terminated

If the client request wrote too many headers, or a header that is too long, in such a way that then terminate parsing, return 431 Request Header Fields Too Large with Connection: close, and close the connection.

It is an important feature that clients are able to provide information opportunistically, even if a server might not use it; so servers should accept many more headers than is needed to fill the request. Most HTTP servers allow a minimum of 100 headers at several thousand bytes each.

Request fully parsed

If the server fully parsed the request headers, but one of the headers is too long for the application to use, it may still indicate this with a 431 status. Include a response body describing the header, its proper usage, and a link to more information.

Reading responses (clients)

The request was not filled. The client may retry the request with fewer or shorter headers, but typically this requires user intervention to determine what part of the request triggered the error.

If the error happens because one of the headers is too long, some headers may be broken apart onto multiple lines. First look at the Cookie header, since its value changes over time at the direction of the server, which may not be aware of the sort of request it's asking the client to make.

In HTTP/2

Similar circumstances in HTTP/2 might instead generate a stream or connection error of x000B (ENHANCE_YOUR_CALM)

Overview table

Name: 431
Message: 431 Request Header Fields Too Large
Description: A request header is too long.
Specification: RFC 6585: Additional HTTP Status Codes §6.5.13. 431 Request Header Fields Too Large

Example

HTTP/1.1 431 Request Header Fields Too Large
Server: httpd/2.4.1
Connection: close

Implementations

Node.js (http/https)

Node.js automatically handles too-long or too-many headers with a 431 status code and a blank body. This error is also generated when the request-line is too long, instead of a 414 (URI Too Long) error. These cannot be distinguished, either by the client, or the application.

A custom response may be sent in HTTP/1.1 responses by listening for the clientError event; request-line overflows, header size overflows, or exceeding the maximum header count will emit an error where err.code === "HPE_HEADER_OVERFLOW". The second argument will be the raw socket, which must be written to, then destroyed.

var http = require('http');
var server = http.createServer(/* ... */);
server.on('clientError', function(err, socket){
	if (socket.writable) {
		if(err.code === 'HPE_HEADER_OVERFLOW'){
			socket.write("HTTP/1.1 431 Request Header Fields Too Large\r\n");
			socket.write("Connection: close\r\n");
			socket.write("\r\n");
		}else{
			socket.write("HTTP/1.1 400 Client Error\r\n");
			socket.write("Connection: close\r\n");
			socket.write("\r\n");
		}
	}
	socket.destroy(err);
});

Two limits are configurable: a --max-http-header-size CLI argument passed to Node.js configures the maximum size of the request-line and each header (this is not configurable at runtime), and the Server#maxHeadersCount property configures the total number of allowed headers.

Apache httpd

httpd sends 400 (Client Error) in this situation. This status code is hard coded in the httpd source, but the LimitRequestFields and LimitRequestFieldSize directives configure the maximum number and size of headers; up to 100 headers of 4094 bytes each are permitted by default.

Fullstack.wiki