The other one is http status codes are http status codes. As in the http request was done correctly, but the application code wasn't. More specifically, http layer was executed successfully, but the application layer was not.
No, this pattern is not the right one for REST. Don't call it REST, call it command/action RPC. The 90s called - they want their architecture back.
It's pretty infuriating actually. On a similar note I have to use certain command line tools provided by a third party vendor that exits 0 on failure, and writes something to STDERR (on success it exits 0 and writes something to STDOUT). The Unix conventions evolved over decades because they were consistent and useful.
But there's an rfc and that's what defines correct usage.
I used to use HTTP status codes in this way because I understood it was the correct REST way of doing things.
However, one day, a sysadmin contacted me to tell me that we had broken a release because our API was returning a 404. Actually it was a problem in the checking script that was checking for data that was no longer in the DB.
By making application codes equal to HTTP status codes, we had removed any way to distinguish between fatal errors and API results.
There was no server-side error. The requested resource was unable to be located because it no longer existed. You should return a 404 here, and not just for non-HTML API clients.
Application-side fatal errors are in the 500 block. So yes, you absolutely can distinguish this case.
I should have mentioned that the API was behind a reverse proxy. This leads to the following questions:
Which requested resource is missing? The API itself or the item requested from the API? How does a client distinguish between these?
If the API itself was not found that’s one of 502, 503 or 504.
200 responses with an error property is an antipattern precisely because of things like reverse proxies. They have no way to unpack and interpret every developers pet error format. They _do_ understand http status codes and can act accordingly, like retrying requests, not caching responses, etc as appropriate.
What if the configuration changes and the API path/URL is no longer in the reverse proxy config? What if the reverse proxy is dynamically configured and our application didn't register itself properly?
They _do_ understand http status codes and can act accordingly, like retrying requests, not caching responses, etc as appropriate.
Of course applications should return HTTP codes when appropriate e.g 500. The principle is that using HTTP codes for application specific information e.g item not found in DB, is a blunt instrument.
They have no way to unpack and interpret every developers pet error format.
I would argue that they don't need to. The conversation is between client and API at higher level than HTTP. HTTP codes are great for information such as "its broken", "please authenticate", "its busy". But HTTP codes are not so useful for things such as "item not in db", "parameter x is missing", "unsupported API version" because this information is nothing to do with HTTP.