Have you ever discussed with your team which HTTP status code is most suitable for the XYZ scenario and then Google the correct status for the use case?
I did it a lot, so I thought to bring it to the table and document it.
There are plenty of resources available over the internet which describes the meaning of HTTP status codes in a single line. But we aim to do reverse, state the use case first and then define the correct response status code for that use case.
There are a total of 41 HTTP status codes defined in HTTP/1.1 Specification [RFC 7231], but in day-to-day development, we encounter few of them.
Common REST API Respons Status
Here are a few use cases which you encounter most during development.
Response of successful GET request, which returns some data. 200 OK
Resource not available for GET Request to fetch single resource by id or other property. 404 Not Found
Resource not available for GET request to fetch multiple/list resources. 200 OK with Empty List/Array
POST request, which successfully creates records and persists. 201 Created
POST request which successfully executes some command/triggers some actions or changes state. 200 OK
GET/POST Request if parent resource does not exist. 404 Not Found
e.g., GET request to get student x of school y
api/school/{school_id}/student/{student_id}
In this case, 409 (Conflict) or 412 (Precondition Failed) seem tempting. But, Conflicts are most likely to occur in response to a PUT request. For example, you may get a 409 response when uploading a file that is older than the existing one on the server, resulting in a version control conflict.
404 (Not Found) seems to be an appropriate response because the schools with school_id does not exist. It's obvious to understand, and you are expecting the same response if api/school/{school_id} is called.
If request-body / path-parameter / query-parameter is missing, any property of them is missing or provided invalid datatype - 400 Bad Request
POST request triggers a long-running asynchronous operation and eventually produces the result. 202 Accepted
Sometimes, considering security, Unauthorized or Forbidden access to some resources can return 404 (Not Found).
Any runtime error / uncaught error. 500 (Internal Server Error)
Following status codes are used by the Web Server, API Gateway, Proxy, or Load balancer. You should not use them in your code.
502 (Bad Gateway)
503 (Service Unavailable)
504 (Gateway Timeout)
Disclaimer
If your team uses some other convention and has used it throughout the existing project, I recommend you stick to it. Changing API conventions sometimes lead to inconsistency in the documentation and may introduce bugs. or if you are in a position to change the convention, you should communicate it with your team.
Closing Notes
Though we briefly listed many everyday use cases, this list can go on. I would like to hear your opinion in the comments.