Why I don't include 404's when designing API's

When designing APIs, one of the most common status codes you’ll come across is 404 Not Found. On the surface, it seems like the perfect way to tell clients that the resource they’re looking for doesn’t exist. But here’s the thing: I don’t use 404 responses in my API designs. It might sound odd, but in my experience, relying on 404 creates more confusion than clarity. Let me explain why.

The Problem with 404 Not Found

At its core, 404 represents something that isn’t there. Whether it’s a webpage that no longer exists or a broken link, the 404 is synonymous with "not found." But when it comes to APIs, 404 can actually conflate two different situations:

1. A typo or invalid URL: If the API endpoint is incorrect, such as a typo in the URL, the server will return a 404, because it literally can't find the resource you're asking for. This makes sense, right? But it’s often unclear to the developer what exactly went wrong.

2. The resource doesn’t exist: This is the case where a resource (like a user, product, or store) simply doesn’t exist in the database. You hit the right URL, but the server can’t find the resource because it’s not there.

Here’s the problem: both cases return the same 404 response, which makes it difficult for the client to distinguish between an incorrect URL and a valid URL where the resource is missing. This ambiguity can lead to a lot of confusion and wasted time trying to debug issues, especially when it’s just a simple typo.

Why This Creates Friction for Clients

When your API returns a 404 for both invalid URLs and non-existent resources, clients have to dig deeper to understand what went wrong:

• Was the URL incorrect?
• Is the endpoint broken?
• Does the resource just not exist?

If the client doesn’t know which situation they’re dealing with, debugging becomes a guessing game. It’s especially frustrating when the problem is something simple, like a typo, but the 404 gives no indication of what happened.

A Better Approach: Clear and Specific Responses

Instead of lumping everything under 404, I prefer to offer more precise status codes and responses, depending on the situation. Here’s what I do instead:

1. Use 400 - Bad Request for Invalid URLs

If there’s a typo in the URL or the endpoint itself doesn’t exist, I return a 400 Bad Request. This tells the client right away that something is wrong with the request they made—not the resource itself. You can also include a detailed message in the response body, making it clear why the request is invalid:

400 - Bad Request

{
  "error": "bad_request",
  "message": "The URL or endpoint you are trying to access is invalid."
}

This is way more helpful than a generic 404 because it gives the client a clear direction: “Check your URL, something’s off.”

2. Use 204 - No Content When Resources Are Missing

For cases where the resource simply doesn’t exist (like a user or store isn’t found), I recommend using a 204 No Content. Why? Because this scenario isn’t necessarily an "error." The API processed the request successfully, but there’s no content to return. This fits perfectly with what 204 is meant for: successful requests with no data to send back.

For example, if a client searches for stores near a postcode and no stores are found, a 204 response makes sense:

204 - No Content

// No body (since `204` doesn’t allow it)

This response tells the client that the request was successful, but there’s simply nothing to show. It’s clean, efficient, and avoids the implication of something being broken.

3. Use 200 OK with Clear Responses When It Makes Sense

In some cases, I’ll return a 200 OK with an empty dataset or a clear message when no resources are found. This works well when the client might expect a body, even if it’s empty:

200 - OK

{
  "status": "success",
  "message": "No stores found near the postcode 12345.",
  "data": []
}

This gives the client more feedback while keeping things clear: the request was successful, there’s no error, and here’s an empty array to show the absence of data.

Why I Avoid 404 Altogether

At the end of the day, the reason I don’t use 404 - Not Found in my API designs is simple: it causes confusion and conflates two very different scenarios. Instead, by using more specific status codes like 400 - Bad Request, 204 - No Content, and 200 - OK with empty results, I can give clients a clearer picture of what’s actually going on with their requests.

This approach reduces debugging headaches, improves the client experience, and keeps the API behaviour more predictable.