Every API MUST use the appropriate HTTP Status Codes to communicate the result of a request operation.
Every API designer, implementer and consumer MUST understand the semantic of the HTTP Status Code she is using.
At a minimum everyone MUST be familiar with the semantics of "Common" HTTP Status Codes.
The 4xx range concerns errors in the API Consumer/Client side, while 5xx range concerns errors in the upstream/backend service or the API implementation.
A request:
GET /orders/1234 HTTP/1.1
...
resulting in the 200 OK response when the requested resource (as identified by request URI) couldn't be found:
HTTP/1.1 200 OK
Content-Type: application/json
...
{
"code": "NOT_FOUND_ERR_CODE"
"message" "Order 1234 wasn't found"
}
is not acceptable.
Instead
HTTP/1.1 404 Not Found
...
should be returned.