At work I’m working on implementing REST based API end-points to expand the functionaity of the front-end application.

Recently I had a discussion with one of the developers in the team about what HTTP error should be used when something that is expected to be present is missing due to some inconsistency in the server.

Suppose you have a resource type called File Resource. Let’s assume that we have two endpoints for this:

  • One to return information about the particular file assosiated with the resource in JSON format (such as file name, size, etc)
  • Otherone to download the file itself

If we have a resource that is identified by the value 1 then the URL endpoints for will look like below:

resource_files/1
/resource_files/1/download

Techincally in the system it should be possible to have a resource file without it’s actual assosiated file.

So the question I had was what error code to return if for some reason the assosiated file is missing for the resource.

Usually we use 404 error code when some resource doesn’t exist and this meant to indicate that the client made an invalid request.

My argument for not to use 404 error code was that since the actual resource is present and only that assosiated file is missing, it should not be 404. Technically the file should have been present as the URL request to the server is valid.

Howeve the other developer’s point was that in this case the actual resource is the file itself and since it is missing we should return 404.

I agreed to disagree and continue to use 404. For our situation it was not a critical issue what error was returned by the server.

However if you are using error codes such as 404 freely to handle error, you might want to consider implications.

One is that the 404 endpoints are typically cached by the browser. So it is possible that the browser would still render the path as 404 even after the server restored the file.

Second thing, when you consider following URLs

/resource_files/99999 --> 404
/resource_files/99999/download --> 404

Both URLs return 404. However you can’t distinguish whether the resource is missing or the actual file is missing for the latter URL. Maybe also it might not be much difference for your application.

The other thing also if you decide to use a different HTTP error code for this edge case, there might not be a suitable one. (See http codes).

So maybe after all 404 is just OK.