Request Header Fields Too Large
ActiveHTTP 431 Request Header Fields Too Large indicates the server refuses to process the request because its header fields are too large. Defined in RFC 6585 §5. May apply to total header size or a single oversized field. Common cause: bloated cookies, large JWT tokens, or excessive tracking headers.
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 response can be triggered in two distinct ways: either the total size of all request headers combined exceeds the server's buffer limit, or a single individual header field is too large on its own. The server is not required to specify which condition triggered the rejection, though well-implemented servers will indicate this in the response body.
The most common real-world trigger is oversized cookies. Session cookies that accumulate state, JWT tokens stored in cookies (especially with large claim sets), analytics and tracking cookies from third-party scripts, and A/B testing cookies can all compound until the total Cookie header exceeds server limits. A user who has been on a site for months may hit 431 while a fresh visitor never does — making this a notoriously intermittent and hard-to-reproduce error.
431 is distinct from both 413 Payload Too Large and 414 URI Too Long. 413 applies to the request body (POST data, file uploads). 414 applies to the request-line itself (the URL path and query string). 431 applies exclusively to the header section — the metadata between the request-line and the body. All three are size-limit rejections, but each targets a different part of the HTTP message.
Server defaults vary significantly: Nginx allocates 4 buffers of 8KB each (32KB total) via large_client_header_buffers. Apache defaults to 8190 bytes per individual field (LimitRequestFieldSize) and 100 maximum fields (LimitRequestFields). Node.js defaults to 16KB total via --max-http-header-size. CDNs like Cloudflare impose their own limits (16KB for headers) that may be stricter than origin servers.
Examples
GET /dashboard HTTP/1.1
Host: app.example.com
Cookie: session=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyXzEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJyb2xlcyI6WyJhZG1pbiIsImVkaXRvciIsInZpZXdlciIsIm1hbmFnZXIiLCJzdXBlcl9hZG1pbiJdLCJvcmciOiJvcmdfYWJjZGVmIiwicGVybWlzc2lvbnMiOlsicmVhZDphbGwiLCJ3cml0ZTphbGwiLCJkZWxldGU6YWxsIiwiYWRtaW46YWxsIl19...; _ga=GA1.2.123456789.1234567890; _gid=GA1.2.987654321.1234567890; _fbp=fb.1.1234567890.123456789; ab_test_variant=experiment_long_name_v2_with_feature_flags_enabled; tracking_id=a]b[c1d2e3f4g5h6i7j8k9l0m1n2o3p4q5r6s7t8u9v0; intercom_session=abc123def456...
Accept: text/htmlHTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
Connection: close
{"error": "request_header_fields_too_large", "message": "The total size of request headers (34,218 bytes) exceeds the server limit of 32,768 bytes.", "hint": "Clear cookies for this domain or reduce the size of custom headers.", "limit_bytes": 32768, "received_bytes": 34218}GET /api/resources HTTP/1.1
Host: api.example.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InJzYS0xIn0.eyJzdWIiOiJ1c2VyXzEyMyIsImlzcyI6ImF1dGguZXhhbXBsZS5jb20iLCJhdWQiOiJhcGkuZXhhbXBsZS5jb20iLCJleHAiOjE3MDk0MDAwMDAsImlhdCI6MTcwOTMxMzYwMCwic2NvcGUiOiJyZWFkOnVzZXJzIHdyaXRlOnVzZXJzIGFkbWluOnVzZXJzIHJlYWQ6b3JncyB3cml0ZTpvcmdzIGFkbWluOm9yZ3MgcmVhZDpiaWxsaW5nIHdyaXRlOmJpbGxpbmcgYWRtaW46YmlsbGluZyByZWFkOnRlYW1zIHdyaXRlOnRlYW1zIGFkbWluOnRlYW1zIiwicm9sZXMiOlsic3VwZXJfYWRtaW4iLCJiaWxsaW5nX21hbmFnZXIiLCJ0ZWFtX2xlYWQiXSwiY3VzdG9tX2NsYWltcyI6eyJvcmdfaWQiOiJvcmdfYWJjMTIzIiwidGVuYW50IjoiZW50ZXJwcmlzZSIsInBsYW4iOiJ1bmxpbWl0ZWQiLCJmZWF0dXJlX2ZsYWdzIjpbImJldGFfZGFzaGJvYXJkIiwibmV3X2VkaXRvciIsImFkdmFuY2VkX2FuYWx5dGljcyJdfX0.signature_placeholder_that_would_be_very_long_in_production
Accept: application/jsonHTTP/1.1 431 Request Header Fields Too Large
Content-Type: application/json
{"error": "header_field_too_large", "message": "The 'Authorization' header field (9,847 bytes) exceeds the maximum allowed field size of 8,190 bytes.", "field": "Authorization", "field_size_bytes": 9847, "max_field_size_bytes": 8190, "suggestion": "Consider using a shorter-lived opaque token instead of a JWT with embedded claims."}Edge Cases
- •431 is intermittent — users accumulate cookies over time, so a request that worked last week may fail today. The same endpoint works fine for new users but breaks for long-time users with cookie bloat.
- •CDNs and reverse proxies may impose stricter header limits than the origin server. A request that passes the origin's limits might be rejected by Cloudflare (16KB), AWS ALB (16KB), or nginx before it reaches the application.
- •HTTP/2 uses HPACK header compression, so the wire size differs from the logical size. A server might accept the compressed headers but the decompressed size could exceed application-level limits, causing a 431 after decompression.
- •Multiple Set-Cookie response headers from subdomains (.example.com) compound into a single massive Cookie request header on subsequent requests. Third-party scripts injecting cookies are a common culprit that site owners don't control.
- •Some servers return 400 Bad Request instead of 431 for oversized headers — either because they predate RFC 6585 (2012) or because their HTTP parser rejects the request before the application layer can classify the error.
- •JWT tokens that embed permissions, roles, and group memberships grow unboundedly as users accumulate access. A user with 50 group memberships may have a 12KB Authorization header while others have 500 bytes.
- •Load balancers may silently truncate headers that exceed their buffer rather than returning 431, causing mysterious authentication failures or missing metadata downstream.
When You'll See This
- →User accumulates dozens of tracking, analytics, and A/B testing cookies over months of browsing, pushing the Cookie header past 32KB
- →JWT access token includes embedded permissions, group memberships, and custom claims that grow to 10KB+ for enterprise users
- →Third-party JavaScript libraries (analytics, chat widgets, ad trackers) each set their own cookies on the same domain
- →Development environment with verbose debug headers (X-Debug-Token, X-Trace-Id with full span context) exceeds limits
- →Microservice-to-microservice calls propagate context headers (tracing, correlation IDs, feature flags, tenant metadata) that compound through the call chain
- →SSO/SAML assertions passed in headers for legacy integrations that embed full user profiles and group lists
- →Mobile app sends custom device fingerprint headers with extensive device capability metadata
Implementation References
| Language | Constant |
|---|---|
| Go | http.StatusRequestHeaderFieldsTooLarge |
| Rust | http::StatusCode::REQUEST_HEADER_FIELDS_TOO_LARGE |
| Python | http.HTTPStatus.REQUEST_HEADER_FIELDS_TOO_LARGE |
| Node.js | http.STATUS_CODES[431] |
| .NET | HttpStatusCode.RequestHeaderFieldsTooLarge |
| Java | 431 (no built-in constant; use HttpServletResponse.SC_REQUEST_ENTITY_TOO_LARGE is wrong — define custom) |
| PHP | Response::HTTP_REQUEST_HEADER_FIELDS_TOO_LARGE (Symfony) |
| Ruby | :request_header_fields_too_large (Rack) |
History
Defined in RFC 6585 (April 2012) §5, which introduced several additional HTTP status codes including 428, 429, 431, and 511. Prior to 431's standardization, servers returned 400 Bad Request for oversized headers with no way for clients to distinguish header-size issues from malformed syntax. The code filled a diagnostic gap that became increasingly important as cookie-heavy web applications and JWT-based authentication pushed header sizes well beyond the limits envisioned in the original HTTP/1.1 specification (RFC 2616, 1999).
Related Status Codes
Related Headers
FAQ
What's the difference between 431 Request Header Fields Too Large and 413 Payload Too Large?
431 applies exclusively to the request header section — Cookie, Authorization, custom X- headers, and all other metadata between the request line and body. 413 applies to the request body (POST data, file uploads, JSON payloads). A 10MB file upload triggers 413. A 40KB Cookie header triggers 431. They target completely different parts of the HTTP message: headers vs. body. Some developers confuse them because both are 'too big' errors, but the fix is different — 431 requires reducing header/cookie size, while 413 requires reducing the payload or using chunked/multipart uploads.
How do I fix 431 errors caused by cookie bloat?
Immediate fix for end users: clear all cookies for the affected domain in browser settings. For developers: (1) audit cookies — remove unnecessary tracking and analytics cookies, set appropriate expiration dates, use sessionStorage/localStorage instead of cookies for client-only data; (2) reduce JWT size — move permissions to a separate lookup instead of embedding them in the token, use opaque reference tokens instead of self-contained JWTs; (3) scope cookies tightly — use the Path attribute to limit which requests include each cookie, avoid setting cookies on the bare domain when they're only needed on a subdomain; (4) increase server limits cautiously — raise large_client_header_buffers in nginx or LimitRequestFieldSize in Apache, but understand this increases memory usage per connection.
Why does 431 only affect some users and not others?
431 is inherently user-specific because cookie accumulation depends on browsing history. A new user has minimal cookies and stays well under limits. A power user who has visited the site daily for 6 months accumulates session cookies, preference cookies, A/B test assignments, analytics IDs, third-party tracker cookies, and potentially dozens of cookies from embedded widgets. Each user's Cookie header is a different size. Additionally, users with many roles or permissions may have larger JWT tokens. This makes 431 notoriously hard to reproduce in testing — developers start with clean browser profiles that never hit the limit.