HTTP Status Codes aren't inherently bad

[jsynowiec]

I came across the section on HTTP status codes, and while I think I understand the author's intent, I’d like to offer a different perspective.

The standardized HTTP status codes maintained by IANA have been in use for over 30 years alongside the HTTP application layer protocol and are a fundamental part of web development. By adhering to these well-established standards, we can significantly reduce cognitive load rather than increase it. These codes are intuitive and easy to grasp—just by glancing at the first digit of the code, we can instantly infer whether the issue lies on the client side (4xx) or server side (5xx), and I'm intentionally omitting the whole aspect of machine-readable replies.

For example, compare the clarity of a standard 400 Bad Request with a hypothetical custom error code like invalid_data_sent_over_http_due_to_unsupported_field_format returned alongside a 200 OK or 500 Internal Server Error code. The former communicates the issue succinctly and universally, while the latter requires additional time and effort to read, parse, and comprehend—time that could be better spent resolving the issue. Not to mention the erroneous state of "correct" or "an error" response indicated by the generic status codes.

Custom, human-readable error codes do have their place, especially when they provide detailed, application-specific context about an issue. However, these should be used as supplementary indicators alongside the HTTP status code rather than replacing it, assuming the communication is happening over HTTP. This approach retains the benefits of a standardized system while adding domain-specific details where necessary, and it is known as Problem Details for HTTP APIs. It was proposed nearly ten years ago as RFC 7807 standard, later superseded by RFC 9457. There are existing implementations in many popular languages.

Standards like HTTP status codes and the Problem Details for HTTP APIs are part of the shared domain knowledge anyone working with HTTP APIs ought to know. Suggesting that such an engineer, regardless if it is a frontend or QA engineer, might struggle to interpret them points to a need for better onboarding or education, rather than a flaw in the standards themselves. Proficiency with such conventions is an essential skill in the industry and promotes interoperability and collaboration across teams.

Customizing systems to suit specific needs is important, but it’s equally crucial to strike a balance by leveraging decades of proven, standardized practices. By using HTTP status codes as a baseline and supplementing them with additional, human-readable error codes, for example, using the Problem Details, we can create systems that are both user-friendly, robust and require a lower cognitive load to grasp.

P.S. The difference between 401 and 403, as well as authentication and authorization, is not a nuance buried deep in some company ADRs, open for interpretation. The 401 response is defined, for example, as part of the RFC 7235 (of course, it is also defined in the original 2068) and can be simplified as "credentials are missing or are invalid". In contrast, 403 means the credentials are present and valid but inadequate (to access the requested resource). There is little to no left to argue about this. Unless we disregard those standards.

I hope this perspective adds to the discussion!

[mikhail-barg]

As far as I understand your point, you are implying that any reasonable developer working with HTTP should have the meaning for all the frequent HTTP codes hardwired into brain. So that it would take not much time to translate from 403 to "you've not enough minerals access rights".

While it's difficult to argue with that, the author's point (if i get it right) is about not having to translate at all.

Which is also not completely achieved with custom error identifiers or messages — as these are needed to be translated/interpreted as well.

[zakirullin]

@jsynowiec These standards can by no means cover all the cases happening in a project. Even if everybody knew much of the standard (which is mentally demanding in itself), they would still struggle to agree on many cases.

The situation I typically observe on projects:

• There are somewhat 20 different HTTP codes used on a project
• Somewhat 12 of them "resemble somewhat close to what is described in the standard", so most engineers understand them straight away
• 4 of them "only partially conform to the standard", they spark debates, they don't reduce our mental activity, subjective knowledge
• 4 of them have nothing similar in the standard, they are domain specific, you just have to remember them

There are hundreds "What is the best HTTP code for ...?" questions. Take this, for example.
I would go for 429, because that's what my mental models tell me to do. But the first colleague I ask prefers 422 more, because his mental models are different. I dive into the code, I see that 429 is already used for the case when there's a version mismatch (when you send an update to an initially stalled version). 422 is used for general validation errors. We discuss it again, we come to some "seems-to-be-logical" numeric status. Will the final numeric status help future developers to understand what's happening right away? Unlikely so.

What is the point of trying to map something that happens in a project to a transfer protocol standard? The taxonomy in the standard tries to be all-encompassing, creating false impression that we can map everything. The problem is that at some point in time that mapping becomes subjective, as such doing more harm than good. We can classify server or client side errors, some other trivial cases, but not more than that.

[johnnyshields]

There needs to be SemHTTP something like SemVer with the following rules:

1xx -> Still processing...
2xx -> OK here's your response
3xx -> Go somewhere else
4xx -> You (the requester) gave us (the responder) a request we can't ever fulfill, at least with the current state of data we have. The requester has within his/her power to resolve the issue by either changing the request, giving up, or some other action. Usually there's no point to retry b/c the same thing will fail.
5xx -> Oops we (the responder) did something wrong. The requester cannot resolve the issue; the responder must fix it. Presumably the requester's request is valid, and if he/she retries the same request after X seconds it may work (i.e. if the issue on our side is resolved.)

When you understand this distinction between 4xx and 5xx ambiguities such as 429 "Too Many Requests" vs. 503 "Server Busy" become clear.

• A 429 is a requester-side error: that specific requester sent too requests and was rate limited (by login session or IP, etc.).
• 503 is a responder-side error; the responder's server is getting hammered, and there's nothing specific a requester can do besides wait for the responder to resolve the issue.

So in a nutshell in terms of cognitive load we only need to concern ourselves with 5 codes (i.e. the first digit 2xx, 3xx, etc)--not hundreds--everything after the first digit should just be helpful clues to ultimately steer both parties to get what they want.

Of course all of this will be badly abused by everyone.