HTTP 431 Request Header Fields Too Large (RFC 6585) indicates the server refuses to process the request because the header fields are too large — either a single header is too long or the combined headers exceed the limit. Common culprit: cookies. As applications accumulate cookies over time, the total Cookie header can exceed server limits (typically 8KB-16KB). The fix is usually to reduce cookie sizes or increase server limits.
Response includes the status code, standard headers (including Content-Type), and a small diagnostic JSON body describing the request and returned status.
Simulator URL (copy in the app after load — not a normal link):
https://httpstatus.com/api/status/431
Example request:
curl -i "https://httpstatus.com/api/status/431"The server is unwilling to process the request because its header fields are too large.
On this code, Inspector focuses on semantics, headers, and correctness warnings that commonly affect clients and caches.
HTTP 431 Request Header Fields Too Large has specific technical implications for API design, caching, and client behavior. Understanding the precise semantics helps distinguish it from similar status codes and implement correct error handling. The response should include a descriptive body following a consistent error schema (like RFC 7807 Problem Details) so clients can programmatically handle the error.
// Handle 431 Request Header Fields Too Large in Express
app.use((err, req, res, next) => {
if (err.status === 431) {
return res.status(431).json({
type: 'https://api.example.com/errors/request-header-fields-too-large',
title: 'Request Header Fields Too Large',
status: 431,
detail: err.message
});
}
next(err);
});from fastapi import HTTPException
# Raise 431 Request Header Fields Too Large
raise HTTPException(
status_code=431,
detail={
'type': 'request_header_fields_too_large',
'message': 'Descriptive error for 431 Request Header Fields Too Large'
}
)// Spring Boot 431 Request Header Fields Too Large handling
@ExceptionHandler(CustomRequestHeaderFieldsTooLargeException.class)
public ResponseEntity<ErrorResponse> handleRequestHeaderFieldsTooLarge(
CustomRequestHeaderFieldsTooLargeException ex) {
return ResponseEntity.status(431)
.body(new ErrorResponse("Request Header Fields Too Large", ex.getMessage()));
}// Return 431 Request Header Fields Too Large
func errorHandler(w http.ResponseWriter, message string) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(431)
json.NewEncoder(w).Encode(map[string]any{
"status": 431,
"error": "Request Header Fields Too Large",
"message": message,
})
}