I've been abusing HTTP Status Codes in my APIs for years

If the API that the author is building is a REST API then the response for a non-existing resource is 404.

In case of REST the main idea is that if you try to GET a resource by ID then you assume that the resource exists. Thus if it does not exists => 404.

It does not matter too much which part of the URL is the one that is causing the URL to be wrong.

Thus `api/v11/employees/1` and `/api/v1/employees/100` both are wrong resources.

In the first case, asking for `/api/v11/employees/1` is not a search or find to see if there is a V11 and if inside there is employee 1. Building an URL is an intentional choise that includes assumptions, like there is an 'api', that has a 'v11' and inside there are employees and one should have the ID 1.

The same goes for later case with employee ID 100. If you ask for an employee with an ID that means you know (or assume that you know) that employee exists. Thus if it does not it should be very level clear => 404.

In both cases responding with 200 means something like "I kind understand that you want an URL that is similar with some that I have so it is almost okish".

But in REST this is not the case. It is like you are serving some static folders and you want to get the file 100 under /api/v1/employee and that file does not exists.

Nobody is stoppping anyone to add response body to a 404 to indicate which nested resource is invalid. That can be added as a debug message for the developer for example.

Of course this is IMHO and I am only addressing REST API. If the API is not supposed to be REST then do whatever you want but make sure you document it well and be consistent.

There is nothing in the protocol that mandates only 2xx status codes are parsable. Instead, the Content-Type pinpoints to the client what kind of content the body has, regardless the status code. And the content-type will most probably be what the client asked (if not, then the server announces that the response content is not subject to negotiation, something that you see rarely nowadays..)

In general I think this post reflects one of the mentalities that appeared around 10 years ago regarding HTTP APIs (another was the extreme hypermedia-driven APIs). But I really think nowadays we can do much better, we can deliver a practical API that works 99% of the times.

By the way in the latest HTTP RFC (RFC9110) status code 422 is finally officially defined (previously was part of webdav extention), which means that the war 422 vs 400 for validation and other semantic errors is over and we have a clear winner. But 200 vs 404 for something that was not found? Well that was has ended long ago I think..

You should detail the error further in the 404 response, and you can say "this entire path prefix could not be found" or just "the path prefix is fine, but this specific employee could not be found". The spec does not prevent you from informing that only the representation of that specific resource is not found. [1]

Using 200 for that is a bit of a cop out, you lose all of the semantics of the response and it's all pushed to out-of-band definitions (like your API's documentation). It could just as easily be argued in the article's example that every single 4xx error is just a 200 with a '{"result": false, ...}' body.

---

[1] - https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4

My highest scoring StackOverflow answer [1] (and my most controversial) is on exactly this topic and _no one_ in any competing answer have given _any_ sensible explanation of their reasoning. I've genuinely never understood their thought process, despite trying really, *really* hard. This explains it a bit, even though I totally disagree.

There are other tools for helping differentiate different varieties of 404 or 401. There are status codes, there's _nothing_ preventing you from returning a payload with explanation or overriding the Reason Phrase. If your HTTP client is too fragile to handle a very common usage pattern for HTTP status codes then pick a different one.

---

[1] - https://stackoverflow.com/questions/11746894/what-is-the-pro...

You can and probably should provide a payload for further processing in some cases, but that's an orthogonal concern.

You are also writing a HTTP server, which provides resources, expects certain formats, provides certain formats, tells intermediate layers and clients about what to cache for how long, says whether a new resource has been created or _will be_ created. You might be redirecting or you might be telling a client that they need to retry a request because there has been a conflict. Your response might be processed by different layers, some of which only care about the status codes, while others will inspect the payload to make further decisions. The list goes on.

Status codes are there so you can do all of these things and more in a standardized fashion. Even just from a human consumption perspective it is useful to just look at the code and immediately have an intuition of what happened.

Also many of the status codes make no sense at all if an application server doesn't provide them. A reverse proxy doesn't know whether there has been a transactional issue on the application server, so it cannot say 409 without that information. A caching layer doesn't know about the domain model so it cannot say whether a specific resource can be cached forever.

One other small gripe I have with this approach is that it reduces the visibility of a failing request in the application layer, which is useful for debugging. It's not uncommon for one of my apps to issue many requests to the app server and if everything returns a 200, I have to look through the various payloads to find the request that actually failed.

I guess my question is: is it really abusing HTTP statuses if it works well overall? I rarely find myself wondering whether a request failed in the network layer or the application layer, I could probably count on one hand the number of times this scenario bitten me in my career. I don't really see the point in throwing out something that works over semantics in an RFC.

For example, https://news.ycombinator.com/s.gif -> 200

But https://news.ycombinator.com/t.gif -> 404

I don't see why /api/v1/employees/3.1415926 shouldn't return a 404 either.

I’ve personally integrated with almost 50 different SaaS APIs in the last 2 years.

The worst ones to work with were the ones returning errors in 200.

I don’t want to parse and write switch statements for your strings to understand whether it’s authentication, authorization, not found or any other error.

Now I have logic tied to strings you return and I can’t wait until someone decides to change the error messages they return. People rarely assume there’s an API contract in error messages.

In general, applications using REST should follow these semantics.

2XX - Request was understood and we found what you were looking for

4XX - Something was wrong with the request on the client side. The client should take some action before retrying.

5XX - Something was wrong with the server and you can retry this request sometime later and it may work.

404: Route not found vs 404: User ID not found seems like it resolves all ambiguity, no?

What if we changed `/some_photo.jpg` to `/photo?id=some_photo` and it didn't exist? 404? Okay, now what if we change `/photo?id=some_photo` to `/photo?id=100`? What if then change that to `/photo/100`? At which point does it no longer become okay for the request to be tied to the resource?

`/api/v11/employees/1` may be 404, and `/api/v1/employees/100` maybe 404 too, because neither of them are found. If anything, the problem is that HTTP status codes are limited and haven't really kept up with technology. We have a few additional codes, like with Cloudflare, but for the most part, there is no community project or standard for expanding HTTP Status Codes.

Perhaps there should be.

I think we need to be using HTTP error codes better at the API layer, not ditching them entirely. Building on this example, for an invalid user, how about an HTTP 204 and an empty response body? That gives us a clear "no such user exists" without having to parse JSON out first.

EDIT: for the record, I think that on some level, REST APIs themselves are an abuse of HTTP. JSON didn't even exist for much of the public Internet's first decade, and certainly the early work on HTTP never mentioned such a thing as a REST API. We're already using HTTP for so many things in so many ways that this is somewhat of a Lilliputian discussion.

Why would we handle not finding an employee differently from not finding an API version?

If we're saying employees/100 should return 200 because it "could" exist, but doesn't at the moment, then why would we ever return anything other than 200? Any route "could" come to exist at a future point.

If you want to do something the author suggests, just abandon REST pathing and do a service call like api/v1/getemployee?id=100

Then the endpoint api/v1/getemployee exists, there’s just no results for your query.

Now for those who are exploring your API with curl or are reading logs from their service they can see the human-legible information that may help them debug the error, while their application logic can continue to use `2xx` for success, `4xx` for my own failure and `5xx` for a server failure that I should retry after some back-off time, allowing it to do the most sensible thing it can in the situation, rather than explode in an uncontrolled fashion when an endpoint the developers only got successful 200 responses from during development suddenly encounters a 200 response with an error payload.

I’ll also point to other status codes like 400 Bad Request or 401 Unauthorized which give a clear reason for why something didn’t work as expected. Under the author’s framework all 4xx responses should be 200.

> The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

(+) This approach reduces ambiguity between failed routes and missing resources

(-) This approach adds ambiguity by making missing resources look like they exist

But what does matter is expectations. People naturally consume lots of HTTP APIs everywhere. And making things like everyone else's doing is important.

Everyone's using HTTP codes for their API. That's reality. So I think that it's better to stick to this format until we'll go some circle and get back to SOAP 3.0 or something.

If you would ask me, I'd prefer distinct set of statuses for APIs. So nginx will never return it, no matter what (mis)configuration happened. Right now if I misconfigure my reverse proxy, it'll return 404 for everything. This should be gateway error, but it's not and some clients will happily work thinking that everything not found which is not true. So something like 1200/1404/whatever for APIs and 200/404 for other things. And author's approach will not help, because it's equally easy to misconfigure nginx to return 200 with some garbage SPA HTML for every request. Well, at least there's hope that failing to parse it as JSON will signal to client that something's not quite right.

HTTP doesn't and shouldn't make a distinction between "this URL maps to a known route on my API backend but the ID doesn't exist on the database" and "this URL is not mapped on my API backend", this is leaking implementation details to the client.

This not "abusing" status codes, this is the expected behaviour for an HTTP server.

It is your API, it is your decision to decide if you have looked for the resource and were unable to find it, so return an error, or you have looked for the resource and found a placeholder that says there could be a resource here, but currently isn't and successfully return that placeholder.

To suggest people are wrong or abusing the protocol for not choosing to implement placeholders in their application is incorrect. To suggest people may benefit from implementing a placeholder instead of a 404 error is useful.

My personal experience is that the error status code here is much more useful than the message. It's a big red/orange flag that says don't do what you normally do with this resource. But if your API lends itself particularly to being queried for things that often don't exist then those red flags become noise that mask other things you really do want to flag as errors.

  /api/v1/employees/100 -> StatusCode: 200

  /api/v11/employees/1 -> StatusCode: 404

You can still include a payload with a 404 describing what is missing or why it wasn't found.

If I see a 2xx status code, I assume the request succeeded. OP's way forces an additional check, more code, more potential for bugs.

I understand what the owner of the API is trying to convey. "My service is up, and the URL itself exists" (status 200), but in the body "the data you requested doesn't exist" (result: true, error: "doesn't exist). If you are stubborn enough, you can even think you're right.

But by Odin's Beard this was one of the hardest APIs I had to work with. It doesn't help that most HTTP clients assume a sane* API expecting error codes based on the resources.

Note: I say sane, but within this context, this is of course subjective. For me, error codes corresponding to the resources is sane, but to OP this is clearly not the case.

Since this makes my firewall dialog pop every couple of seconds after I close it, I prefer to close the page without reading it.

Why not just serve it over 443 as well?

There's nothing wrong with that, and many implementors and applications have certainly taken the tack the author suggests -- i.e. use HTTP strictly as a simple transport layer rather than a representation of application state -- GraphQL is a great example.

But the rfc is pretty darn clear: "The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists."

I can't find a reasonable interpretation of this that somehow means if the server can't find the document you asked for, you should still return 200.

You know what happens next. If a client generates too much business errors, the load balancer tends to throw out a server, which doesn't bother the client in the slightest, except it has to login again for the next request. Keep this up for a few minutes, and it makes all but 1 servers disappear from the pool, and the only survivor to spend half its time negotiating connections.

After knocking it around in my head, I concede I am wrong :) HTTP is, after all, an Application layer protocol.

Whilst I remain unconvinced by some of the arguments, that one that got through to me was mostly about the reasoning behind using an application layer protocol in the first place: standards. And this breaks the crap out of those standards.

The correct answer is probably closer to a combination of status codes and a _clear_ response message (as well as the correct Content-Type header!)

An empty 404 is ambiguous, which is surprising to nobody :) fair points all round

Just another reason I'm a big fan of GraphQL - error handling is much more clearly defined, with responses returning a 200 and the body defining the error.

If your API was: `GET /api/v1?employee=1`, then returning 200 with a `{ result: false }` for employee 100 makes sense, because a resource identified by the URL `/api/v1` exists, but the parameter asks for something that doesn't. And `GET /api/v11?employee=1` returning 404 is also consistent, as there is no `/api/v11` resource.

However, by setting your API to `GET /api/v1/employees/1` you're saying that each employee is resource identified by a URL, and so using HTTP status codes to say whether that resource exists is consistent with the way that API uses URLs.

The way you're using status codes isn't intrinsically wrong. It would make absolute sense if your API used URLs in a way that complemented that usage. The only problem is that you aren't.

I am wondering, do you have one endpoint per API version, or one endpoint per resource type? i.e. Should `GET /api/v1/xyzzy/1` return 200 or 404 if there is no `xyzzy` resource type? What if you decide to change your architecture and split a monolithic API into multiple services? Or do the opposite?

This approach is the HTTP-server equivalent of exposing a function that sometimes returns null.

When you call a function like that in your code, the call succeeds and returns, but the caller needs to now inspect the returned object to see if it is actually useful.

In this case, the HTTP call succeeds, but you now have to parse the result to figure out whether you got something useful.

In code, there are a few alternatives to having a function returning null: throwing an exception, the null object pattern, or the optional type/maybe monad.

Using an HTTP status code lets your client choose an HTTP client implementation that manifests as one of these, according to their preference, simplifying their code.

So just from an application design point of view... if you wouldn't build a function with that return signature, why would you build an HTTP endpoint that does that?

I like to do 2 layers of checks, (1) Is the site returning a 200? (2) Can the site return a specific file?

This script will send me an email alert if the site is not returning a 200 status code, but it's easy to daisy-chain other commands too.

Here's an example of (1):

#!/usr/local/bin/bash

INPUT="/usr/sync/urls.txt"

#DOWN="down.txt"

TODAY="$(date +'%Y-%m-%d_%R:%S')"

while read line ; do

status_code=$(/usr/local/bin/curl -o /dev/null --silent --head --write-out '%{http_code}\n' $line)

if [ $status_code -ne "200" ]

then

echo "$line is down since $TODAY" |mail -s Site_DOWN email@example.com

#echo "$line at $TODAY is DOWN" >> $DOWN #example to output to a file.

#You can add further actions here

fi

done </usr/sync/urls.txt

Ultimately I think why this is so confusing is because HTTP error codes are confusing and they should be clearly defined and/or include more codes specific to application errors rather than the network. It makes life much easier when you can see immediately the type of error you receive and if I had to depend on my API producer to write sensible error messages using 200 return codes I'd lose my mind.

GraphQL — where you are sending and receiving data (and application errors) to a specific endpoint is much much saner.

My take is that this kind of architecture might be fine for personal applications, but once you start working with other people this can get infuriating very fast (I know I was). Others already mentioned why this would be a bad idea (caching, etc.), but for me the most important thing is that it's not conventional. I don't know of any open source web framework that handles http statuses this way out of the box. If someone does please comment so I can have a look.

Because most people abuse status codes, most tooling is built around status codes. All of the Java HTTP libraries, for instance, throw very nice and easily-handle-able exceptions for non-200 status codes, but do nothing at all for 200 codes. So, now, we need to:

* try/catch the call anyway, because it might fail * parse the result * figure out if the result is an error or OK * throw / return early from error results * separate that throw from the try above

It's all so much hassle to avoid a mistake that _client libraries don't make_ : using the wrong URL in the first place.

If you care about your callers and they're internal trusted partners, you can return a traceId header they can use to diagnose the 404 to find out if the request was malformed somehow or the requested ID was truly missing or something else bad happened. Splunk can be a pretty rad thing when everyone is on the OpenTelemetry bandwagon. Otherwise, assume the caller is evil and treat them accordingly.

You should return the best-fitting error code and an error response in an expected format for the end user you are serving (either your own frontend, or your own api users).

Using 200 for everything means you can't use a whole lot of enterprise server / error tracking software to monitor failures related to the business logic, which are generally as important as most technical failures.

That's basically arguing against REST and for RPC over HTTP

https://github.com/lightninglabs/aperture

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

On one team we once also came up with a compromise where we would use 2 status codes. 200 for all success, 400 for all errors. However I would prefer HTTP status codes just go away altogether. Those are for the web browser software to do things like navigation, not for APIs. Same with HTTP verbs.

Aside from the theoretical reasons why status codes aren't good for APIs, there's also a practical reason. Using the same status code for all intentional results is best because it allows the clients to write simpler error handling code. If they get a 200, then they also get a payload describing success or failure. If you get any other HTTP status, it's an unexpected or unknown error. If you were to instead use many HTTP statuses, each one comes in the known and unknown varieties, where the error description payload may or may not be there. In the simplest cases, this is equivalent. But in a more complicated case, where you many have more than 2 HTTP errors and also more than 2 application-level errors described in the payload, it becomes difficult to handle all the errors correctly.

Since I'm obsessed with telemetry data, as any seasoned engineer eventually will be, the conflation between HTTP error data and application error data is vexing in logs and telemetry. In older APIs I work with, the errors are all conflated in this way--errors were being tracked and categorized in some cases simply by their HTTP status. But there's 400s, and then there's 400s. There were unexpected 500s, and then there were 500s we understood and could have added data to. Sometimes a transient 500 could actually be understood as a 400. The results are not correct, and they would never be correct because it is not manageable.

People get so enamored with trying to make REST APIs into this rigorous thing. The REST thesis was an old academic trick where Fielding just described the way web browsers work, but changed all the specific nouns into spooky abstract ones. Most of the ceremony around HTTP trappings like status codes and verbs are there for the browser and are white elephants, obstacles, when trying to write an API.

If you need to differentiate between a technical error and a business domain error, we have other tools: A whole list of 4xx errors can be used for slightly different semantics (400 for "Bad request", 422 for "Unprocessable entity", etc). And we can attach a response body to a response of any status code, not just a 200. I'd definitely try these tools first rather than break HTTP semantics.

If you are using graphql or jsonrpc or something, then sure return a 200 "The request was ok, but go look in errors"

If you are using REST then I think it is fine to return a 404 - "The thing you wanted doesnt exist". That seems correct to me, the thing you wanted to get doesn't exist.

The fact that /non-existant-path also returns a 404 is also correct, the thing/resource you wanted doesn't exist.

- https://datatracker.ietf.org/doc/html/rfc7807

HTTP transports content, and the content is your API. HTTP should not be part of your API

Why not merge them and work with lists, I think a lot people would intuitively understand the following:

GET /users?ids=1

{ "users": [] }

GET /users?ids=1,2,3,4

{ "users": [ { "id": 3 } ] }

Transport the ids in any way you like, that's not my point.

Ideally, the bad paths all are caught during dev-time but that just can't be assumed to always happen, it doesn't account for any of the risk involved with other systems changing and then 404's popping up. It could happen for other unexpected reasons so why should we assume it won't, it seems like we're just covering our eyes to the problem.

for a short example, Imagine a brand-new account was made in a system. should it make some sort of GET request for a specific component of its account that is created asynchronously to the rest of the account creation, eg a 3rd party billing service, and receive a 404 from the server, there are different interpretations that the client could have around this error code! does it mean one such component was truly not created and needs to be? could it be that as a client we know implicitly of this delay and fudge a 404? using 404 as a catch all for these cases seems error prone and less informative than returning the true results of the GET request. I posit that any good client-side software handles 0 results from a request with an empty state, and 1 or more with a results state and 4XX with the error state(s). its more clear, trustworthy and easier to debug.

Example: https://news.ycombinator.com/item?id=31849488

Putting the API version in the path of a request is not a good solution. Doing it introduces exactly this kind of ambiguities that could be avoided without them.

I would like to point out a few of the detractors are conflating REST and HTTP RPC, I avoided using the term REST for a reason :)

BUT, that being said, lots of good arguments against this stance. I appreciate the feedback :)

  status: 404, 
  body: {
      "result": false,
      "errorMessage": "No employee found for ID 100"
  }

  /api/v1/employees/<employee_id>

There is an API being provided, specifying how to craft the URL, among other things. It’s not a “resource” at all, it’s a function call, and the difference becomes extremely evident as soon as you start needing to add variations to the request using query parameters.

Good APIs have few nouns and many verbs. That’s exactly the opposite of REST, which says you should have many nouns (URLs) and few verbs (HTTP methods).

REST is a misguided idea that an academic had years ago. It doesn’t work well and it certainly doesn’t represent some philosophical ideal. We should stop pursuing it.

A 404 should not be shown on a valid path with an empty result. That’s exactly what 204 is meant for.

Moreover, a 404 in many REST clients will bubble up an error in the application code because it thinks there’s something wrong (you’re trying to reach something in the wrong place). That’s not the case for an empty result, any more than an empty list is an error.

Feels cleaner to me, and while I want to argue about the opinionated payload bit, I suppose that's something that should be clearly defined in the contract anyway.

Maybe I've been abusing status codes too...

> [...]

> As an API consumer, all I want to do here is raise my middle finger.

Why? As an API consumer this makes sense to me. The author doesn't go into any detail on why it presumably doesn't make sense to them, nor what problems it presents from a client implementation standpoint?

> RFC 7230 defines HTTP as an Application Layer protocol, which means it should represent application logic, right?

No. What? No. Why on earth would it mean that. It's a protocol at the application layer - it has nothing to say or do w.r.t. the internal implementation details of that application. Why on earth would it?

None of this article makes any sense whatsoever. The author is making some wild assumptions that seem entirely unique to themselves - I've certainly never seen anyone else face these logical challenges.

> In any API call, there are 2 problems to solve as a client when you are processing the response:

> 1: Did the technical request succeed?

> 2: Did the business/domain request succeed?

Where in your client code are you trying to solve these problems? Is it in the same place? If so, you've over-generalised / over-DRY-ed your error handling.

If you've approached writing your client in a sane manner, you have business/domain context at the request site - you can tell the granularity of your request validity by the code location where you're handling the response.

As a developer of client code, 4xx means "I did something wrong". It's not the server's responsibility to know how I've implemented URL-building and whether or not I'm using dynamic version strings. Take the author's example:

/api/v1/employees/100 -vs- /api/v11/employees/1

Here's 2 ways I could build that URL (pseudocode):

  base = '/api/v1'
  section = '/employees'
  url = '$base/$section/$id'

  v = '1'
  url = '/api/v$v/employees/$id'

---

As for the solutions proposed, there's two problems:

Problem 1 (harmless enough): The error context provided in the 200 response body will only be specifically useful for the author's example client implementation - many different clients will consume your API and their implementations will differ. For some of them, the context will be of less/no use (coupled with added developer confusion from the unexpected statuscode).

Problem 2 (harmful): This kind of context is going to enable OSINT user & metadata enumeration in a very large number of API applications, so recommending this as general advice is actively dangerous.

I don't like the design of REST. I don't think status codes should have meaning to an application. Why? Because there is not a defined status code for every type of problem.

One thing I have often run into is: what status code are you supposed to use when business rules aren't followed? Let's say the resource exists, so it's not a 404, and the request is properly formatted as JSON and all the fields have valid values, so it's not a 400. But the user is trying to do an invalid action, like booking an appointment slot that is already full. What status code are you going to use?

For this reason, I've seen two types of code bases that use status codes. The first one is error handling soup:

    if (res.statusCode == 404) {
        // Display a "not found" error to user
    } else if (res.statusCode == 400) {
        // There will probably be some validation errors in the body, so display those
    } else if (res.statusCode == 403) {
        // show a "forbidden" error to user
    } else if (res.body.error) {
        // Aha! We have some error that doesn't have a defined status code.
        // This block will contain a completely different type of error handling,
        // based on information found in the body.
    }

    if (res.statusCode != 200) {
        // Error handling reading information from res.body
    }

So my solution is to always have a boolean value called "ok", and if "ok" is not true there's always a human-readable error you can show to the user.

    if (!res.body.ok) {
        // Show res.body.error to the user
    }

There are only two places where I use status codes.

If some unexpected error happens (like the database is down), I return 500. If my frontend ever sees 500 it sends the error to my error reporting system.

If the user is not authenticated I return 401. If the frontend ever sees 401 it automatically redirects the user to the login screen.

Importantly, both of these things are hidden away in a library I wrote, so my application code never thinks about them. It just thinks about !ok.

Status codes work for things that are generic from the point of view of the client, in the sense that the client doesn't care if my database is down or if I misconfigured something or if I ran out of memory. It only cares if "something bad happened that needs to be reported to the devs", which is 500, or "this user is no longer logged in so they need to log in", which is 401.

For everything else, the client does care about the specifics of what the error means, so I need to pass it that information. Status codes don't work for that.

The thing with response codes is that they are often logged in contexts where it is unpractical to read and parse the response body. Like for rate-limit rules in layer 7 proxies and so on.

404 are overused though. Sometimes it is better to design around the problem to only get “real” 404:s so to say. 204:s can also be used even though any REST fanatic will disagree with that.