REST API Best Practices: Using Proper Status Codes

8 min readDec 5, 2021

APIs make the world go round. I’m not exaggerating. So many fundamental things in this world rely on the proper communication and information exchange between computer systems across the globe. For most of this system to system communication, REST APIs have become an industry standard.

This is so significant, that even the term “API Economy” was coined.

Major cloud providers like AWS, expose their services to their global users through a set of API calls.

REST, although over 20 years old, is still the dominant methodology for creating web APIs. Ever though it’s principals are older than many developers implementing them, there still seems to be a lot of bad practice in many APIs that are massively used.

I’ve decided to write a series of articles about REST API best practices, and I will start with a topic that is very important, yet very often not implemented properly — using proper status codes.

Too often have I seen an API return a 500 status code, when the request clearly failed due to a client error, not a server error. Or, even worse, you get a 200 status code, with a response body of

{'error':'bad request'}

Status codes are there to make the API user’s life easier, not more difficult.

So, let’s go over the status codes your API needs to use, in order for it to be properly constructed.

400 Bad Request- this one should be pretty common in your API, because you will always return it whenever the request sent from the client is not properly constructed. Also, apart from the status code, you need to send a descriptive message about what the client has done wrong ( more about that in one of the next articles in this series).Please, never return just a 400, without a detailed explanation of why the request is invalid.

For example, you have an endpoint that a user can call to get a list of football teams. However, this endpoint mandates that a country query parameter is passed along the request. So if the client just calls: