Two reasons why using 200 instead of 404 can make sense:

- No way to distinguish between the api client calling the wrong URL eg /mytypo/12345 instead of /myquery/12345. With 404, the client will not realise their mistake without debugging.

- Lots of 404 errors can trigger security sensors. Having to whitelist 404 in a security sensor can be a pain to convince the team that manages them. Doubly so if they are part of the other company rather than yours.

Aside from slightly less code to write, what benefit does 404 bring?

With a 200 your client won't know they've done anything wrong without debugging either. There is nothing preventing you from returning a detailed error message with your 404.

If under your suggestion you have to look at the details of a 404 anyway to get a detailed error message, what is the point of the 404? Your client always has to do an explicit check for error/no-error. Why make them check two different locations? Just always look at the body: one location.

If the 404 is due to the client calling the wrong URL, rather than trying to access an entity/record that doesn’t exist, the client code will incorrectly assume the entity/record doesn’t exist when it actually does.

Eg an API has a /discountvoucher/ID, so your client can enter a discount voucher code and get info on the voucher. If your client code calls /voucher/ID instead, under the 404 approach you would incorrectly think the voucher doesn’t exist, when it does.

If using the other approach, you have this code in the body, you would know straight away that the URL itself is wrong because you’d have no JSON body.

So in the former approach the client code would be oblivious to the error until someone realises, maybe years down the track, that the code is calling the wrong URL. In the later approach you would know immediate as the client will receive a body content it’s not expecting and throw a fit.

Yes you could return 404 as the http status code and embed the code into the body, but that brings us back to why do both? That opens up for lazy programmers to just check the first and not the second.

> If the 404 is due to the client calling the wrong URL, rather than trying to access an entity/record that doesn’t exist, the client code will incorrectly assume the entity/record doesn’t exist when it actually does.

There's the root of your error: the entity is the URL; the URL is the entity. If the client requests a URL which does not exist … that URL does not exist.

If the client requested a URL which does not fit the expected schema … that URL does not exist.

Once you embrace RESTfulness & HATEOAS, life gets so much simpler. Also, every time you return errors in a 200, God kills a kitten. If for nothing else, think of the kittens!

Because they can pull extra information out that can help them understand why they're receiving a 404. The lack of information can itself become a signal.

> -No way to distinguish between the api client calling the wrong URL eg /mytypo/12345 instead of /myquery/12345.

More often than not, this distinction matters less than one might think. In either case, you've got an upstream problem for the client: how it's determining the `mytypo` portion of the path or how it's fetching invalid identifiers. This is actually part of the point of the philosophy behind REST.

But if caring about fine distinctions is the point here, there's no appreciable improvement between using 404 for both "something's bad about the path" and "path's good, no resource here" and using 200 for both "path's good, no resource here" and "everything's fine!" Especially when, personally, I think the distinction between "I got back data!" and "I didn't get back data" is more important than "I didn't get back data for reason X" vs "I didn't get back data for reason Y."

Now, maybe you don't agree with that prioritization, or maybe you'd argue "Oh, I just handle did-vs-didn't-get-data situations both under 200 with a message somewhere in the response body." Cool. As my earlier comment points out, you can do that in the response body of a 404 too.

So of course it is quite possible to make distinctions between why a 404 error code happens, just the same as it is for what kind of 200 you're getting back.

And you can still go straight status header on top of that too: make your own 4xx for "resource not found even though URL is correct", maybe something like 434. Or if you're queasy about that sort of improvisation, use 400 with a status message in the body about an invalid id. Or if you're absolutely sure for some reason that it should be 2xx, consider 204 (though it sure seems like a bad id is a form of client error).

> Lots of 404 errors can trigger security sensors. Having to whitelist 404 in a security sensor can be a pain to convince the team that manages them.

I might well have a side-eye for a security team that sets its thresholds here too aggressively, but OTOH, a client that is generating a lot of 404 errors on legit URLs is either broken or it's getting fed bad ids by the API... or it is in fact malicious. In each case eyebrows should be raised. Hopefully any security layer is also sending back a useful status code and response body to the client.

> Aside from slightly less code to write, what benefit does 404 bring?

Like I said in my earlier comment, out-of-band broad status code can let you switch between error handling pathways well before you've spent time parsing a more detailed message in the body (which you may or may not get, depending on the error condition!), or even for specific error messages you have never thought of much less seen. Knowing what kind of error you're dealing with before you know the deep specifics is really useful across a variety of software situations.

And there's so much web tech and tooling that's set up to see 200 as "Everything is Fine, You Got What You Wanted!" You're working against the related infrastructure when you use 200 to indicate an error condition. You're working with it when you use HTTP status codes.

> And parsing that message field and checking conditionals to determine your client's behavior is something you'll have to write code for unless you're just relaying the error message back to the end user.

Oh noooo, you have to.... handle errors coming out of API's you consume. What an imposition... It must be terrible to be you, always having to write code to handle when things don't go exactly down the happy path.

> Might be better to have the HTTP error code and prepare your client to read responses based on multiple content types.

yes! Imagine seeing a 500 and knowing for sure that there's a server misconfiguration. Being able to trust http status codes: it's what's for dinner.

> Oh noooo, you have to.... handle errors coming out of API's you consume. What an imposition... It must be terrible to be you, always having to write code to handle when things don't go exactly down the happy path.

Do you really think this is a conversation about never wanting to handle errors, or is that sarcasm as a convenient way of getting out of actually thinking during the discussion?

Good specific HTTP status codes from the application layer help the client sort errors by type before they have to parse specifics. Or in cases where the client may not even have been prepared for the specifics.

Have you really never found a software situation where it's useful to know what the type of error is before you get into the details?

If that's the case, you definitely shouldn't be anywhere near API design.

> Imagine seeing a 500 and knowing for sure that there's a server misconfiguration.

Imagine knowing there's a whole range of 5xx status codes that allow for both that possibility and others.

> Being able to trust http status codes: it's what's for dinner.

Well, I'm glad we've gotten here, given that you seemed to start with "200 all the things, sort it out in the response body."

> Do you really think this is a conversation about never wanting to handle errors, or is that sarcasm as a convenient way of getting out of actually thinking during the discussion?

It was me making fun of someone trying to argue that you would have to write code for the non-happy path in scheme A, but not B.

> Good specific HTTP status codes from the application layer help the client sort errors by type before they have to parse specifics. Or in cases where the client may not even have been prepared for the specifics.

> Have you really never found a software situation where it's useful to know what the type of error is before you get into the details?

Yes, because you could never embed that sort of information into the JSON, that's not what it's for! It's for... well I guess if you're not using it for that sort of information I don't know what it's for.

> Imagine knowing there's a whole range of 5xx status codes that allow for both that possibility and others.

https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_...

11 5xx status codes. I'm glad to know these cover all possibilities for the software you write, but you know what's even worse than anything we've discussed here?

15 different API's defining 512 to mean different things specific to their software. All in the name of software cleanliness, because parsing json is apparently icky and hard in brainfuck, their API language of choice I guess?

> because parsing json is apparently icky and hard in brainfuck, their API language of choice I guess?

It's quite clear that what I'm talking about here has nothing to do with the ease of having a piece of software parse JSON, but with the difficulties introduced by thumbing your nose at helpful conventions in a context where "rough consensus and running code" has been brilliant at enabling a spectacular network of interconnected clients and servers.

It's less clear why you'd insist on returning to characterizing these points as "oh, you think JSON parsing is hard", but some of what it could indicate isn't flattering. Whether you're content with that or rueful about it at some point might also say something, though with any luck I will no longer be among those evaluating it.

> 11 5xx status codes. I'm glad to know these cover all possibilities for the software you write

Not my claim. My claim is that existing status codes cover some broad categories, and by recognizing what your status conditions have in common with existing HTTP codes, you can do early sorting across condition categories, and work in cooperation/re-use with other pieces of code and infrastructure.

> but you know what's even worse than anything we've discussed here? 15 different API's defining 512 to mean different things specific to their software.

Which of course applies equally to your individualized in-band error codes... that sword you were swinging cuts both ways, right? Except, of course, that they're not really exactly equal situations: if you 200-plus-response-body all the things, a client developer has to learn not only what your custom error codes mean without the benefit of working from HTTP-related conventions/groupings that you apparently won't engage, but they have to figure out which property/s they're passed back under when there's already a perfectly good standard for these things in the header information.

Contrast that with the situation of a developer who is working on a client that gets a status code header 512 back from an API written by someone who groks and tries to work with status code groupings. Even if the client dev has no idea what the server means by 512 specifically, they already know that it's not related to a user input or even a client request problem, and more importantly, code already written to deal with other 5xx errors either for this client or other clients knows at least that much too. If it turns out general 5xx handlers aren't adequate, they can turn to docs and/or response body info to learn more about 512 condition specifics and augment the general case with specific handlers (however rare the case may be in which a client might need to do anything other than relay API status messages).

> Yes, because you could never embed that sort of information into the JSON, that's not what it's for

You certainly could. You could also put all the other header information into the response body, too... Content-Type, Cookie info, Authorization headers, CORS, etc. For some reason people don't. Hell, I'll bet even you don't. Perhaps you'll ask yourself why. Perhaps not.

> It was me making fun of someone trying to argue that you would have to write code for the non-happy path in scheme A, but not B.

This isn't even an accurate summary of your comment, let alone an adequate characterization of or response to mine.

Good luck with your own happier paths. If you're as much more correct than I am about this topic as your rhetoric (if not your logic) seems to imply you believe you are, then I'm sure your decisions will be their own reward.