What's the most appropriate HTTP status code for an "item not found" error page

Question

I'm curious what's the most appropriate HTTP status code for an "item does not exist" page.

If the page itself doesn't exist, I'll obviously use 404. However, one of my pages has a userid argument (it's an "edit user" page) and in case no user with the given user ID exists I'm displaying an error page, but I'd also like to send a 4xx status header (since "200 OK" doesn't really fit).

I guess 404 would be ok since it's "not found" and not "file not found", but I wonder if there's a better code for this case.

Answer 1

The previous answers lack nuance and yet require a lot of reading to understand the differences.

Rule of thumb:

• 404 when the page or endpoint itself is missing
• 404 when the endpoint is present and the query got properly processed, but produced no results AND THAT'S MEANT TO BE AN ERROR

(e.g. querying a user on its ID and you know the ID is supposed to exist)

• 204 when the page is present and the query got properly processed but produced no results AND THAT'S OK

(e.g. searching users by date of birth and it just so happens that no user has this date of birth. That's not an error, an empty result is just one possible result -- and will just display an empty results table in the frontend)

204 is very nice for modern REST APIs ...But make sure that your frontend knows to tell the difference between 200 and 204 if that's relevant!

In your case it seems like 404 is better as it's a page (not an endpoint) and trying to access a non-existing user is supposed to make the application raise an eyebrow.

Note that in the modern age, most backends are able to generate a "404" page that displays a pretty message and other useful things when the item is not found. As a result, fancy people would configure their backend so that there is an even more specific "not found" page for users. In other words, the Users URL would not generate the default, pretty 404 page when the user does not exist but instead return an alternative version of that page, showing a pretty message along the lines of "this user does not exist".

Answer 2

204 is the appropriate solution when the item is not found because the 404 status code will throw even uncreated APIs.

404 Status Code:

404 status code automatically appears when the requested API is unavailable. Links that lead to a 404 page are often called broken or dead links and can be subject to link rot.

204 Status Code:

204 status code should be when the item is not found which means your request processed successfully and the content not found.

Answer 3

404 is just fine. HTTP Status Code Definitions from RFC9110

Answer 4

If the page itself doesn't exist, I'll obviously use 404.

What you said there is a bit confusing but I will have to assume that you're developing an API backend.

The problem is that whoever is consuming the API endpoint may be confused in two ways:

1. They may think the 404 returned is because the endpoint(resource) wasn't reached, Or
2. They might think that the item or user being requested wasn't found.

So the trick is, how are they going to know which is the right assumption?

Well, the answer is simple. Always try to attach a body to any errors that you returned from code. Errors that are returned by the server automatically do not have a body. So try to attach a body which you can document so that they can be able to use the content of the body to differentiate between code returned errors and server errors.

But in a nutshell, 404 is the right status to return, but try to attach a body to it indicating why 404 was returned.

An example could be:

// For illustration I'm just gonna use C#
Return NotFound(new { errorMessage: "Item requested was not found" });

Here, NotFound returns a 404 statuscode and the parameter is an object like { errorMessage: "some reason for the error"}. This way, you can always check if your error returned a body, and the you know it's returned from your code. Otherwise, the resource(link) wasn't found.

Answer 5

Since it's a user-facing page always use 404. It's the only code people know usually.

For the api request, use 400 with the error message "No such user exists" or something along those lines.

Answer 6

/**
* {@code 422 Unprocessable Entity}.
* @see <a href="https://tools.ietf.org/html/rfc4918#section-11.2">WebDAV</a>
*/
UNPROCESSABLE_ENTITY(422, "Unprocessable Entity")

Answer 7

204:

No Content.” This code means that the server has successfully processed the request, but is not going to return any content

https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204

Answer 8

That's depending if userid is a resource identifier or additional parameter. If it is then it's ok to return 404 if not you might return other code like

400 (bad request) ‐ indicates a bad request
or
412 (Precondition Failed) e.g. conflict by performing conditional update

More info in free InfoQ Explores: REST book.

Answer 9

A 404 return code actually means 'resource not found', and applies to any entity for which a request was made but not satisfied. So it works equally-well for pages, subsections of pages, and any item that exists on the page which has a specific request to be rendered.

So 404 is the right code to use in this scenario. Note that it doesn't apply to 'server not found', which is a different situation in which a request was issued but not answered at all, as opposed to answered but without the resource requested.

Answer 10

Getting overly clever with obscure-er HTTP error codes is a bad idea. Browsers sometimes react in unhelpful ways that obfuscate the situation. Stick with 404.