Do you make these small mistakes with HTTP status code?

Just last week, I was having a code review session with a new Intern at my work place. He was visibly enthusiastic with how much and he has learnt in very short time and I was happy for him.

I asked him to walk me through the features he's built which he did, but since he was more focused on Backend, I asked him to abandon chrome and test his work with POSTMAN.

Everything was going well until we saw this:

Can you spot the issue?

Returning a 200 OK status code for a Not found page

The big issue

Over and over again, I see this problem among developers. And lately, it's becoming increasing common. One reason is that, software learning is structured as other fields, most people are self thought and it's easy to learn things wrongly and run with it.

Another reason is that, habits die hard. It's very hard to take a U-turn once you are on the wrong path. It takes a great deal of will — more than what was required to start it.

Using the wrong HTTP Status code has big implication: Misleading communication between the server and client. This can result in confusion, incorrect assumptions, and potentially compromised functionality.

So it's essential that you convey the right info to the client.

That's what this article will help you do!

Through practical examples and explanations, I will share common pitfalls and mistakes related to HTTP status codes that developers may fall into, and also how to resolve them.

This article will help you leverage HTTP status codes in ensuring accurate and meaningful server-client interaction, enhancing user experience, and adherencing to best practices in web development.

When you are done reading, you will get clarity on what to do. And you will know what HTTP Status Code to return in the most situations you will find yourself as a backend developer.

Common mistakes and how to avoid them:

1. The "200 OK" for error responses:

This is the example I pointed out in the intro, and it's a common problem among developers. Instead of returning the correct error code, they return an inappropriate "200 OK" status code.

This can be misleading as the client will interprete it as a success when it's in fact, an error. It can also be frustrating to users when they are searching for the failure point inorder to address the issue.

If the requested resource is not found, respond with a 404 Not Found status code, indicating that the requested content could not be located.

Alternatively, if the request itself is invalid or malformed, the server will return a 400 Bad Request status code, indicating that the request could not be understood or processed correctly.

2. Returning a generic 500 Internal Server Error without providing more specific information

I don't know which HTTP status error code I hate the most: 402 — reminding me that I'm poor or the elusive "500 Internal Server Error" without additional specifics or details.

I recall a particular incident when we encountered a 500 Internal Server Error, assuming it was an unforeseen software bug. However, after extensive investigation, it was discovered that the error stemmed from an incorrect database configuration. The lack of informative error messages significantly prolonged the debugging process, causing unnecessary frustration and confusion.

In situations like these, it becomes evident that merely notifying users about the presence of an error is insufficient. It is crucial to guide them in understanding and resolving the issue with actionable error messages — That's how you ensure good user experience.

3 The "301 Moved Permanently" without proper redirection:

Using the "301 Moved Permanently" status code indicates that a resource has been permanently moved to a new location. But you will often see developers used this code without actually redirecting the resource or provide incorrect redirection URLs.

Not only is this frustrating to users who can't access the resources, it will also have an impact on your SEO (Search Engine Optimizations).

So double-check your redirections when using this status code.

4 The excessive use of "302 Found" for all redirects

Some developers use the "302 Found" status code as a catch-all for all types of redirects. But all redirects are not equal!

There are situations where a "301 Moved Permanently" is appropriate while a "308 Permanent Redirect" isn't. ** this will ensure the correct behaviour.

5 Using 403s/404s for rate limiting

Some API developers mistakenly use 403 Forbidden or 404 Not Found HTTP status codes as a means of rate limiting.

However, this is considered inappropriate usage of these status codes since the 4XX range of status code except 429 imply that there's something wrong with the user's request which is not the case here.

Instead, return a 500, 503, or 429 HTTP status code. This is also what Google recommends in reducing their bot crawl rate

Moving On

HTTP status codes are designed to provide high-level information about the outcome of a request. However, relying solely on them without accompanying error messages or response bodies can make it challenging for developers or users to understand the cause of an error.

Providing clear and helpful error messages alongside appropriate status codes improves the debugging and troubleshooting experience.

These are just a few examples of how HTTP status codes can be misused or misunderstood. It's always important to consult the HTTP specification and best practices documentation to ensure that you're using the appropriate status codes in your applications and providing meaningful information to users and clients.

Quick Trivial

• If you have an API that queries an SQL DB, and the SQL DB returns no results, what HTTP status code would you set?
• What error do you throw if someone is not registered?
• When you delete a resource in your DB, what should be the success status code?
• When your API creates a new user, what HTTP status code do you return?
• What is the HTTP status code to send when the request was successful but the response does not contain a payload or redirection?
• If a pirate website was cracked down by the Feds/Law, what error code should they return to clients?

Let me know your answers in the comment section