HTTP

431 - Request Header Fields Too Large

Getting a 431 Request Header Fields Too Large means your request headers exceeded the server's size limit—too many cookies, large custom headers, or cumulative header size is too big. This client-side error (4xx) happens when servers enforce header size limits (typically 8-16KB) to prevent buffer overflows. Most common when Cookie headers accumulate and grow large, but also appears when custom headers contain too much data, multiple authentication tokens are sent, or debug headers add excessive size.

#Common Causes

→Frontend: Cookie header too large (many cookies accumulated). Custom headers contain large data. Multiple Authorization headers. Debug headers add size. Headers exceed browser/server limits.
→Backend: Server header size limit too restrictive. Header validation rejects large headers. Buffer size configuration too small. Server doesn't support large headers.
→Infrastructure: Nginx/Apache header buffer limits. Load balancer header size restrictions. API gateway enforces header limits. WAF blocks large headers.

✓Solutions

1Step 1: Diagnose - Check DevTools Network tab Request Headers—calculate total header size. Review Cookie header size. Count number of headers. Check custom header sizes.
2Step 2: Diagnose - Server logs show header size exceeded. Review server header buffer configuration. Check Nginx/Apache limits. Verify infrastructure header limits.
3Step 3: Fix - Client-side: Remove unnecessary cookies. Split large cookies. Compress or remove custom headers. Delete debug headers. Reduce header count.
4Step 4: Fix - Server-side: Increase server header buffer size. Configure appropriate header limits. Return 431 with size information. Add header size monitoring.
5Step 5: Fix - Infrastructure: Increase Nginx large_client_header_buffers. Configure Apache LimitRequestFieldSize. Update load balancer header limits. Review WAF header size rules.

</>Code Examples

Fetch API: Optimize Headers to Prevent 431

1// Client-side: Optimize headers to prevent 431
2function optimizeHeaders(headers) {
3  const optimized = { ...headers };
4  let totalSize = 0;
5  
6  // Calculate current header size
7  Object.entries(headers).forEach(([key, value]) => {
8    totalSize += key.length + (value?.toString().length || 0) + 4; // +4 for ": " and "\r\n"
9  });
10  
11  // Typical limit is 8-16KB
12  const MAX_HEADER_SIZE = 8000;
13  
14  if (totalSize > MAX_HEADER_SIZE) {
15    console.warn(`Headers too large (${totalSize} bytes), optimizing...`);
16    
17    // Remove debug headers first
18    delete optimized['X-Debug-Info'];
19    delete optimized['X-Trace-Id'];
20    delete optimized['X-Request-Id'];
21    delete optimized['X-Request-Start-Time'];
22    
23    // Optimize cookie header (often the culprit)
24    if (optimized['Cookie']) {
25      const cookies = optimized['Cookie'].split('; ');
26      // Keep only essential cookies (first 10)
27      optimized['Cookie'] = cookies.slice(0, 10).join('; ');
28    }
29    
30    // Remove or compress large custom headers
31    if (optimized['X-Custom-Data']) {
32      // Remove large custom data or compress it
33      delete optimized['X-Custom-Data'];
34    }
35    
36    // Remove duplicate headers
37    const seen = new Set();
38    Object.keys(optimized).forEach(key => {
39      const lowerKey = key.toLowerCase();
40      if (seen.has(lowerKey)) {
41        delete optimized[key];
42      } else {
43        seen.add(lowerKey);
44      }
45    });
46  }
47  
48  return optimized;
49}
50
51// Usage with automatic optimization
52async function fetchWithOptimizedHeaders(url, options = {}) {
53  const optimizedHeaders = optimizeHeaders(options.headers || {});
54  
55  const response = await fetch(url, {
56    ...options,
57    headers: optimizedHeaders,
58  });
59  
60  if (response.status === 431) {
61    // Headers still too large - try with minimal headers
62    const minimalHeaders = {
63      'Authorization': optimizedHeaders['Authorization'],
64      'Content-Type': optimizedHeaders['Content-Type'],
65    };
66    
67    return fetch(url, {
68      ...options,
69      headers: minimalHeaders,
70    });
71  }
72  
73  return response;
74}

Express.js: Configure Header Size Limits

1// Server-side: Configure header size limits
2const express = require('express');
3const app = express();
4
5// Middleware to check header size
6const checkHeaderSize = (req, res, next) => {
7  let totalSize = 0;
8  
9  // Calculate total header size
10  Object.entries(req.headers).forEach(([key, value]) => {
11    totalSize += key.length + (Array.isArray(value) 
12      ? value.join(', ').length 
13      : value.toString().length) + 4;
14  });
15  
16  const MAX_HEADER_SIZE = 8192; // 8KB default
17  
18  if (totalSize > MAX_HEADER_SIZE) {
19    return res.status(431)
20      .json({
21        error: 'Request Header Fields Too Large',
22        message: `Total header size (${totalSize} bytes) exceeds limit (${MAX_HEADER_SIZE} bytes)`,
23        maxSize: MAX_HEADER_SIZE,
24        actualSize: totalSize,
25        suggestion: 'Reduce cookie count or custom header sizes',
26      });
27  }
28  
29  next();
30};
31
32app.use(checkHeaderSize);
33
34// Or use express built-in limit (if available)
35// app.use(express.json({ limit: '10mb' }));
36// Note: Express doesn't directly limit header size, use middleware above
37
38// Log large headers for monitoring
39app.use((req, res, next) => {
40  const headerSize = JSON.stringify(req.headers).length;
41  if (headerSize > 4000) {
42    console.warn(`Large headers detected: ${headerSize} bytes from ${req.ip}`);
43  }
44  next();
45});

Nginx: Increase Header Buffer Sizes

1# Nginx: Configure header buffer sizes to prevent 431
2http {
3    # Increase header buffer sizes
4    client_header_buffer_size 4k;
5    large_client_header_buffers 8 32k;  # 8 buffers of 32KB each
6    
7    server {
8        listen 80;
9        server_name api.example.com;
10        
11        location /api/ {
12            proxy_pass http://backend;
13            proxy_set_header Host $host;
14            proxy_set_header X-Real-IP $remote_addr;
15            
16            # Pass all headers (within buffer limits)
17            proxy_pass_request_headers on;
18        }
19    }
20}
21
22# Or return 431 for oversized headers
23# server {
24#     # If headers exceed large_client_header_buffers, Nginx returns 431
25#     # Custom error page
26#     error_page 431 /431.html;
27#     location = /431.html {
28#         return 431 '{"error":"Request Header Fields Too Large","message":"Headers exceed server limit"}';
29#         default_type application/json;
30#     }
31# }

↗Related Errors

400 414

Provider Information

This error code is specific to HTTP services. For more information, refer to the official HTTP documentation.