Skip to content

431 Request Header Fields Too Large

Description

The 431 Request Header Fields Too Large status code indicates that the server is unwilling to process the request because its header fields are too large. The request may be resubmitted after reducing the size of the request header fields.

This status code is commonly used when: - The total size of request headers exceeds the server's limit - A single header field is too large - There are too many header fields in the request - Cookie headers contain excessive data

The 431 Request Header Fields Too Large status helps servers protect themselves from potential denial of service attacks involving extremely large headers, as well as from implementation bugs that might cause memory issues when processing oversized headers.

Syntax

The server responds with a 431 Request Header Fields Too Large status:

HTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Request Header Fields Too Large",
  "message": "The server is unwilling to process the request because its header fields are too large"
}

Examples

Excessive Cookies Example

A client sends a request with too many or too large cookies:

Client Request: 

GET /api/data HTTP/1.1
Host: api.example.com
Cookie: session=very_long_session_token_value; preferences=extremely_long_serialized_user_preferences_data; tracking=very_long_tracking_id; analytics=long_analytics_data; [many more cookies...]
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36
Accept: application/json

Server Response: 

HTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
Content-Length: 187

{
  "error": "Request Header Fields Too Large",
  "message": "Cookie header exceeds maximum allowed size of 8KB",
  "suggestion": "Clear your cookies for this domain and try again"
}

Too Many Headers Example

A client sends a request with an excessive number of custom headers:

Client Request: 

GET /api/resource HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
X-Custom-Header-1: value1
X-Custom-Header-2: value2
X-Custom-Header-3: value3
[... hundreds more custom headers ...]
X-Custom-Header-500: value500

Server Response: 

HTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
Content-Length: 215

{
  "error": "Request Header Fields Too Large",
  "message": "Request contains too many headers",
  "max_headers": 100,
  "your_headers": 503,
  "suggestion": "Reduce the number of custom headers in your request"
}

Large Authorization Header Example

A client sends a request with an excessively large authorization header:

Client Request: 

GET /api/secure-data HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...[extremely long token with thousands of characters]
Accept: application/json

Server Response: 

HTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
Content-Length: 243

{
  "error": "Request Header Fields Too Large",
  "message": "Authorization header exceeds maximum allowed size",
  "max_size": "8KB",
  "suggestion": "Use a shorter token or consider using a different authentication method",
  "documentation_url": "https://api.example.com/docs/auth"
}

Summary

The 431 Request Header Fields Too Large status code is an important mechanism for servers to protect themselves from requests with excessively large headers that might cause performance issues or memory problems. It provides clear feedback to clients that they need to reduce the size or number of headers in their requests. This status code is particularly relevant for applications that use large cookies, complex authentication tokens, or numerous custom headers. By responding with this status code, servers can guide clients toward making more efficient requests that stay within reasonable size limits.