This week was the first time I encountered status code 431 and did some research into it as we were seeing it happening in a few places. I thought I'd share my findings so that if you're encountering this issue, you've got a good starting point.

What does it mean?

According to the MDN website:

The HTTP 431 Request Header Fields Too Large response status code indicates that the server refuses to process the request because the request's HTTP headers are too long. The request may be resubmitted after reducing the size of the request headers.

431 can be used when the total size of request headers is too large, or when a single header field is too large. To help those running into this error, indicate which of the two is the problem in the response body — ideally, also include which headers are too large. This lets users attempt to fix the problem, such as by clearing their cookies.

In other words, something on the server that is hosting the particular file that you are trying to access is objecting to the fact that the request that is being made is too long.

In my experience though, the error doesn't mention which headers are the problem so you'll generally have to do a bit of digging to figure that out.

How long is too long?

This is a good question and it varies depending on what is running the website that is causing the error.

If the site is hosted on S3, with a CloudFront distribution in front of it, it has a limit of 8KB. Whereas if the site is a Node.js application, it'll have a limit of 16KB (from v14 onwards anyway).

So you'll want to research what length of HTTP request your particular flavour of server will accept.

What is the cause?

Referring back to the MDNwebsite, it mentions that:

Servers will often produce this status if:

• The Referer URL is too long

• There are too many Cookies sent in the request

From doing quite a bit of research into this, cookies often seem to be the culprit here so it's worth checking whether this is the case if you're encountering this issue. If someone is seeing the issue in their normal browser window but it goes away in incognito, that is definitely a hint that cookies might be a problem.

How to replicate the error

If you're seeing reports of this error but can't replicate it yourself, try adding some cookies using Dev Tools for whatever browser you are using. You can generate some lorem ipsum text and use that, but make sure it isn't too long as browsers have limits in terms of how long cookies are allowed to be.

Note: you can calculate the length of a bit of text in bytes using this short JavaScript snippet:

(new TextEncoder().encode('insert your string here')).length;

Once you've set the cookies, try refreshing the page to see if the error appears.

How to fix it

The sticking plaster fix is to get the user to clear their cache - this will reset the cookies and hopefully bring them back down to a manageable level. However, you can't always ask users to do this, so you may want to find a more long-term solution.

It is difficult to say exactly what this solution will be because it depends on what kind of server you are using, but you will want to reduce the number of cookies being sent somehow. Whether that is using CloudFront to strip them away, not using as many cookies on your site or creating a session cache to store data in instead, it all depends how much capacity you have and how much refactoring you are able to do.

In any case, I hope this article gave you some ideas and helped you debug a particular issue. If you have any questions, do feel free to leave a comment!