This decision diagram may be useful, but the fact that it is required at all is ridiculous.
Instead, we should just use the generic
x00 status codes for all responses.
Note: I am talking about “RESTful” APIs here. Most of this does not apply to regular websites serving browser traffic.
For successes (2xx)
There is no real difference, from an API consumer’s perspective, between a
200 OK and a
202 Accepted. The client knows which endpoint it is calling; it
knows that this particular endpoint handles requests asynchronously. The same
applies to the
201 Created status code.
204 No Content is a bit different, as in this response is not allowed to
contain a response body, according to the HTTP/1.1 spec. The
problem is that some web frameworks allow sending a body with this status code,
leading to problems when the response is processed by some component that does
not expect a response body. We can avoid this problem entirely by sending a
200 OK response with
Content-Length: 0 when sending a response with no
For client failures (4xx)
In most cases, the status code, by itself, is not enough to understand what
caused the error. A
405 Method Not Allowed needs to specify which methods are
413 Payload Too Large still needs to include an acceptable size to be
However, if we are going to send good error messages anyway, the status code provides no real value. A well-written API consumer would ignore the specific status code and instead parse the response body to determine which error occurred, and why.
Furthermore, providing a status code may encourage clients to create half-baked solutions that try to guess what caused the error by only looking at the status code, instead of properly reading the response body.
All in all, for most client errors, we should return a generic
400 Bad Request, along with a descriptive error message (and, if possible, a
documented, unique string that allows programmatic processing of said error).
For server failures (5xx)
For server-side errors, the API consumer cannot do much. In fact, providing additional information to the client may be a security concern, as it reveals server-side implementation details to potential attackers.
For most server-side errors, a
500 Internal Server Error is all a client needs
to know, along with a request ID such that it can be sent to the API developers
to aid in debugging whatever caused the error.
It really is that simple, an API only ever needs to return three error codes:
400 Bad Request, and
500 Internal Server Error. We do not need to
fuss about which status code to use.