431

Request Header Fields Too Large

4xx Client Error

Back to list.md

ELI5

Your request headers (the extra information like cookies) are too big for me to handle. Clean up your cookies or make the headers smaller.

Server perspective

Use 431 when one header field or the total request header section is too large to process.

When to use

  • •Return 431 for oversized Cookie, Authorization, or accumulated proxy headers
  • •Use it when the problem is header size rather than body size or URI length
  • •Request headers exceed server limits
  • •Too many cookies causing large Cookie header
  • •Authorization headers that are too long
  • •Custom headers that exceed size limits
  • •Accumulated headers from proxies

How to respond

  • •Tell the client whether one specific header or the overall header set is the problem when possible
  • •Set clear size limits across proxies and app servers to avoid inconsistent failures

Headers to consider

  • •No status-specific header is required; still send normal HTTP metadata such as Content-Type, caching, or tracing headers when they help the client.

Response body

  • •Identify the offending header or total header limit when that can be shared safely.

Server-side pitfalls

  • •Do not use 431 for bad header syntax; use 400 for malformed headers
  • •Do not confuse oversized headers with oversized bodies or URLs
  • •Request body too large (use 413 Content Too Large)
  • •URI too long (use 414 URI Too Long)
  • •Bad header format (use 400 Bad Request)

Examples

Excessive cookies

Request:GET https://api.example.test/api/data # Headers Cookie: session=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Response:431 Request Header Fields Too Large # Headers Content-Type: application/json # Body { "error": "request_header_fields_too_large" }

Cookie header size exceeds server's 8KB limit

Large Authorization header

Request:GET https://api.example.test/api/users # Headers Authorization: Bearer <very-large-jwt>
Response:431 Request Header Fields Too Large # Headers Content-Type: application/json # Body { "error": "request_header_fields_too_large" }

JWT token size exceeds server's header size limit

References

Related Status Codes

400

Bad Request

Your request doesn't make sense or has mistakes in it. Check what you're sending and try again.

413

Content Too Large

The file or data you're trying to send is too big for me to handle. Please make it smaller.