431 - Request Header Fields Too Large
HTTP 431 Request Header Fields Too Large means the server rejects request headers because they are too large.
Last reviewed: February 22, 2026|Editorial standard: source-backed technical guidance
What Does Request Header Fields Too Large Mean?
Header metadata exceeded what the server or intermediary accepts, so requests are rejected before application logic can run.
Common Causes
- -Combined JWT and custom headers exceed Nginx large_client_header_buffers capacity configured on ingress.
- -Cookie accumulation from analytics and feature flags pushes Cookie header size beyond gateway hard limit.
- -Proxy chain duplicates x-forwarded-* headers on each hop, causing cumulative header growth and rejection.
How to Fix Request Header Fields Too Large
- 1Identify oversized headers (often cookies or custom metadata) and trim them immediately.
- 2Reduce cookie scope/size and remove redundant client-sent headers.
- 3Align header size limits across CDN, proxy, and origin to prevent path-dependent failures.
Step-by-Step Diagnosis for Request Header Fields Too Large
- 1Capture full header set and compute per-header plus aggregate byte size at failure point.
- 2Determine whether rejection is caused by one oversized field or total header budget exhaustion.
- 3Compare size limits configured on every hop (browser/client, CDN, ingress proxy, origin server).
- 4Retest with minimized headers and reintroduce optional headers incrementally.
Header Budget Attribution
- -Identify top contributors to header size (example: cookie blob grows past 12 KB due to accumulated feature flags).
- -Distinguish single-field overflow vs total-header overflow (example: one JWT header too large even when aggregate is within limits).
Infrastructure Limit Alignment
- -Audit limit mismatches across hops (example: CDN accepts 16 KB headers, origin proxy enforces 8 KB).
- -Validate compression/normalization side effects (example: duplicated forwarding headers inflate aggregate size).
Implementation Examples
curl -i -X GET https://api.example.com/v1/resource -H "Cookie: session=$(python - <<'PY'
print('a'*12000)
PY
)"
# Response:
# HTTP/1.1 431 Request Header Fields Too Large
# {"error":"Request Header Fields Too Large","code":"431"}const response = await fetch('https://api.example.com/v1/resource', {
method: 'GET',
headers: { 'Accept': 'application/json', 'X-Debug-Blob': 'a'.repeat(12000) }
});
if (response.status === 431) {
console.error('Handle 431 Request Header Fields Too Large');
}import requests
response = requests.get(
'https://api.example.com/v1/resource',
headers={'Accept': 'application/json', 'X-Debug-Blob': 'a' * 12000}
)
if response.status_code == 431:
print('Handle 431 Request Header Fields Too Large')How to Verify the Fix
- -Resubmit requests with reduced headers and confirm 431 is cleared.
- -Run boundary tests at documented per-field and aggregate header limits.
- -Validate behavior remains stable across browser, mobile, and server-side clients.
How to Prevent Recurrence
- -Set explicit header budgets per client and enforce cookie hygiene policies.
- -Add automated tests for per-header and aggregate header-size thresholds.
- -Continuously monitor header-size percentiles and growth trends by route.
Pro Tip
- -treat total cookie size as a tracked performance/error budget metric so header bloat is caught before 431 incidents.
Decision Support
Compare Guide
HTTP 400 vs 422: Bad Request vs Unprocessable Content
Fix API payload issues faster by using 400 for malformed syntax and 422 for semantic validation failures, so clients correct format before business rules.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Playbook
Validation Failure Playbook (400 / 422 / INVALID_ARGUMENT)
Use this playbook to separate malformed-request failures from semantic validation failures, then fix request contracts without broad server-side bypasses.
Official References
Provider Context
This guidance is specific to HTTP services. Always validate implementation details against official provider documentation before deploying to production.