Is HTTP 404 (not found) fail or error?

[sheldonh]

We are finding it difficult to agree on the correct jsend status for an HTTP 404 response. Could the spec clarify this somewhat special case?

Two schools of thought here.

• It's the client's fault, so it's fail, with data set to something like {"message": "Route not found"}.
• The client can't change the request params and try again.

I've taken a look at some implementations, and there seems to be some consensus for HTTP 404 being error. However, my reading of the spec is that it should be fail.

[artyuum]

Late reply but here is my opinion. I'm considering it as a "fail" in my apps because I think that if the client requests a resource that does not exist, it's not the server's fault. Even if this resource used to exist but not anymore, I still consider it as a "fail".

Hope it helped.

[f1ncc]

Well, I think it should be considered as an "error". Because it has always been a popular phrase among the people who use internet who say, "I got this 404 error".

[artyuum]

@f1ncc Nope, considering it as an "error" goes against the specification, as stated:

Error
When an API call fails due to an error on the server.

A 404 status code is not a server error.

[mihazelnik]

@artyuum But then based on specification, only 5xx errors should be error, since all other status codes are not server error?

How about failed login? Will you send back status: fail but what will you return in data, since you only want to return Wrong email/password msg. Its making more sense that calls where all you will do is return msg back should be error 🤷

[artyuum]

only 5xx errors should be error, since all other status codes are not server error?

Yes.

How about failed login? Will you send back status: fail but what will you return in data, since you only want to return Wrong email/password msg

Yes. Usually, you add more information in the response than a simple error message. For example, when the form validation fails, I send the following as response:

POST /api/images

{
    "status": "fail",
    "data": {
        "image": "This value should not be blank.",
        "name": "This value should not be blank."
    }
}

And if you still need to output a simple message, it should be fine to add it into the "data" field, as follow:

GET /api/unknown-route

{
    "status": "fail",
    "data": "Not Found"
}

[asiby]

I think that a 404 when retrieving a resource for your clients is a JSend fail.

I see an error as something usually unexpected that could happen. For example, someone calls your API using Ajax using some missing parameters. Basically, at that point, the request will be malformed and even if the resource that they want to interact with does exist, you cannot even process the request. An example for that would be an API call using the wrong method (ex. PUT) when your API endpoint doesn't handle the PUT method. That would be a JSend error.

If the request successful ran without anything that you would have logged in the backend (in errors logs for example), then it's not an error. It's just a case of the customer not getting the result they hopped to obtain (login failed, unauthorized to access a resource, resource not found, etc).

In the context of Ajax using jQuery, I do the following:

jQuery.ajax({
  // some settings
})
.done((data, textStatus, jqXHR) => {
  // I expect the JSend success or JSend fail here.
})
.fail((jqXHR, textStatus, errorThrown) => {
  // I expect the JSend error here whenever possible.
})
.always((data) => {
  // Some processing
})

Even with what I have mentioned, some errors will not be coming from your API. A network level error could cause the Ajax call to fail and call the fail() callback ... And that will not follow the JSend format.

At the end of the day, just create a convention that works for you and put a line of comment in the code that can help developers using it.

[bbsimonbb]

In my fork, I'm going to add a fourth top level status, "empty". It really is a special case, perhaps the most common of the non-successes. Making it a top level status will clear up all the discussion and give an unambiguous way to test, and, like for the 2 other non-success statuses, encourage consumers to think about and code for the case.

[primadi]

if we are using jsend, when 404 happens, is server return status code 404, or status code 200 ?