You can distinguish between them in your response body. A simple error response body for a JSON-oriented REST API is often something like a JSON object with a human-readable error message, and a unique code for that type of error. i.e. {“message”:”No such route”, “code”:”ad01fd04-8e9e-4326-9576-3d479fa20637”}

This is where error response messages should come into play. Returning a JSON object with a "message" attribute containing "No such route/path" vs "Object not found" depending on the context of the 404 makes it immediately clear where the issue is.

I'd propose either 421 Misdirected Request or 400 Bad Request, both with more detailed error message in the body when the URI Path is incorrect and doesn't map to anything, and 404 Not Found for valid requests for things that don't exist.

From a client application perspective, would you want to handle the cases differently?

Of course, hitting a path without a handler is a bug, a resource which doesn't exist is a normal thing.

The situation you describe is not really REST. In REST, URLs are opaque; they have no structure for clients to understand. So, clients don't make up new URLs in order to determine whether resources exist. They only use URLs that they've already been given. If they haven't received it, they don't care whether it exists. This is called "Hypermedia as the Engine of Application State".

If doesn't exist means it has been removed: 410 Gone, if doesn't exist means not yet created: 404 Not Found.

I can't think for other types of not existing, or why you'd need to differentiate between them.

Say I have an API with a path of /customer/<id>.

I call /customer/235235 and customer 235235 doesn't exist. That's a 404, resource not found.

But say I make an uncaught error with the path and call /cutsomer/235235. That also is a 404, resource not found.

It really depends on what you want the word "resource" to mean.

It gets a bit more complex if you have a simplistic website with an API service both on the same server. For your users, you want a nice 404 page for mistyped or dead links. But you don't want your API also triggering that same page.

Beyond actually splitting your main web content and API into two servers, I could see returning a 400, Bad Request response for the API to avoid triggering a 404 handler. After all if you give it a customer ID in the above case that doesn't exist, it is essentially a "bad input parameter" and the error message can indicate which parameter (the customer ID) and why it's a problem (there is no such customer).

I've seen this type of reply in previous posts on this thread, and I am baffled at the fact that people seem to have their downstream users be much closer to the API than I think it's safe.

To answer the specific question /cutsomer/123 should never be hit in a production application, unless your user actually inputs that, so treating it differently is just overhead that gives no benefit.

Also for the "both on the same server" scenario, you can make a pretty good assumption if a user agent is a browser or an API client, so you can present the right output to the right one. The accept header is the simplest method I can think of.

> It really depends on what you want the word "resource" to mean.

I once worked with an old API and when a pentest team ran a scanner against it they reported hundreds of backdoors and malicious code false positives because they were expecting a 400 error rather than an 200 with success=false response body

valid path: maybe return 200 (the request is ok), but return an empty object.

invalid path: 404

You don't

I can just see some developer going nuts and pulling out their hair because they can't figure out why a call to query a customer keeps saying the customer doesn't exist when clearly it is in the database. Until they realize they gave the URL path as "/cutsomer" instead of "/customer" in the code.