> I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors.

If all of your errors line up perfectly with HTTP, I guess this could work. But if you've got something that doesn't fit, or two things that would map to the same one, it gets weird.

And then you have http client libraries that do great things like only return response bodies if status 200, or only return http statuses they were aware of. It's not very RESTful to just return http 200 with an embedded application status, but it's easy and consistent, and I would not write an HTTP api otherwise, unless I was had a good reason to follow some existing spec that used statuses.

It depends. I've seen bigco use this technique and their reason was that they wanted to separate problems with API and request from actual issue with their servers/platform. So if you get 200 it means they received request successfully but if there is issue with request they'll include error in response with 200. If it's anything else then there is a networking or delivery problem. It's not standard way to handle things but can be useful at times.

If the server got an issue with your request it can return 400 (Bad Request), which means that the server has received it successfully before acknowledging it as a bad one.

Even then, if the server returns 400 (Bad Request) the server can still attach a response body to that, in plain text/plain, application/octet-stream or even application/json, which could contain elaborate information.

This is what the 400 and 500 ranges of HTTP status codes are for.

The former when the problem is on the client side, the latter for a problem on the server.

And you can still send a descriptive body for the error, if you so choose.

This is not true. Counterpoint, responses like 404 or 503 Bad Gateway do not come from the destination server. They do not indicate the intended server received your request.

404 and 500 should come from the destination server. You are correct that 503 would not.

Hmm are these assumptions valid? Can't a misconfigured load balancer cause a 404? Couldn't a bug in nginx, node or an app server produce a 500 response outside of your control?

I suppose a misconfigured load balancer or nginx instance could return absolutely anything. I think you'd have to be actually maliciously misprogramming it, though, to reach that level of dysfunction!

For example, suppose you want to distinguish between a missing/deleted resource /myuser/23123 and a completely invalid query /muser/23123.

Both of these are 404 (or 410 for permanent caching) responses according to HTTP, though they have very different reasons for "non-existance".

No, the "completely invalid query" is 400.

404 is only for "the request makes sense but that specific resource doesn't exist".

400 is a very generic error. It is often used to complain about problems with the request body.

Considering how brief the HTTP RFC is, your interpretation is I think as good as any, if very uncommon. (Not what Django, Rails, Flask, etc. do).

In this case it’s a 404 because the query URL pattern doesn’t exist - the most common cause of 404s.

Same thing, no? If I ask for /api/user/238885 and I get a 404 back, it's because the resource "user" with ID of 238885 doesn't exist. If I ask for /api/banana/wharrgarbl, it's because the resource "banana" with the ID of "wharrgarbl" doesn't exist.

How is this better than using different status codes depending on the type of problem?

>I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors.

So here's the deal with this pattern...If you're returning a typed error response, something the client application should interpret, you want to be able to know which error responses will actually have that body and will not be a generic error like a 404 or a 503. If the response code is 200, you can be generally sure that the response came from the target host. Thus, the client knows they can parse an api level error from a 200 response and they should not attempt to parse non-2XX responses. I don't love the pattern but its not completely pointless.

Does anyone know if the HTTP spec guarantees codes in 4XX range should only come from the intended host? It seems like 400 is a safe bet but I've never double checked myself.

The client should try to parse the response body only if it has the appropriate Content-Type header value. It should not assume that responses with various status codes have a particular body format.

Do you suggest having a content-type header specific to your app? Something like "application/my-app+json"? Will most tooling handle this correctly? In my experience the always 200 api style is a lot more common.

I've found that returning 200 with errors seems to be the sane way to do things, since sometimes it's difficult to tell whether a server error belongs in the http later or graphql layer.

> When pointed out, the support answer was "we chose to give meaningful error messages instead of HTTP codes, that's why we respond with 200 in case there's an error in the request". Not the answer I was expecting.

I don't see the problem here. As a developer I'd much rather receive a standard json packet with information helping me figure out what went wrong.

I really don't understand your complaint here, I've designed and worked with both types of API's, and I find the standard json format to be far easier to deal with.

Totally agree that specific messaging is very convenient, but meaningful error messages and meaningful status codes aren't even remotely mutually exclusive. It's perfectly legitimate and even easy to send a 4xx or 5xx with a response body as JSON (or, for bonus points, with any other content type the client requests from possible server capabilities).

And in my experience, having an out-of-body/band general indicator that doesn't require you to parse message responses makes things WAY easier.

Well-designed APIs do both.

I'm curious, what tech stack are you working in where parsing json is difficult?

You want to talk about inconsistent? How about a 500 error may or may not result in the standard response format you're expecting because it may be coming from the server and it may be coming from the API.

I'd much rather my 500 errors be legitimate server problems.

While we're asking questions: what stack out there makes reading/writing HTTP headers hard? Because that's all it takes to work with response codes.

And yes, of course parsing JSON isn't difficult. Note that I said parsing messages -- the message field not the response body. 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.

Now, if you have an HTTP error code, you already know something about why the error condition is happening before you look at any part of an error message field. For example, if it's a 4xx error, and you know that your client generated the associated request to the API using user data, then you can probably just pass the error message straight back to the user w/o parsing it and going through your own error message logic (although that depends on the quality of the API too).

> How about a 500 error may or may not result in the standard response format you're expecting

Well, in that case, relying on some message field you might have supposed would be in a specific JSON response isn't going to help you much either.

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

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.

You don't have to. Plenty of times, a 404 is all I need to know. Why make the client check two different locations?

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.

Whether there's a bug in the underlying API code, or a bug in the web server, there's a risk that it "may or may not result in the standard response format you're expecting", and therefore... should be a 500 error.

Yes, using the wrong status codes is a problem, you're right, that's the entire point of the thread you're responding to.

that's flat out not true, it's a red herring.

I can't think of very many tech stacks where an error inside the API couldn't be trapped and responded with a standard json response.

>but meaningful error messages and meaningful status codes aren't even remotely mutually exclusive

They actually are. Things besides your app code can response with 404 and 503 but not your error body. 4XX and 5XX bodies must be parsed more carefully and cannot be assumed to have a consistent structure with the same level of trust a 200 response would.

Http codes are nice but it makes api error parsing much more complex so there are some trade offs.

Monitoring tools logging request/response payloads are just going to look at status codes. Breaking that kind of stuff cos you wanted to do it your way sucks.

I guess I've never worked with a monitoring tool that didn't support deserializing json and looking for specific data.

A huge and borderline criminal conflation with HTTP in general and REST-y APIs.

The big fat elephant in all this is simple; None of our fucking opinions matter one god damn bit to the end client. Being originally designed to you know, consume hypertext over the hypertext transfer protocol, clients can and will do whatever the fuck they want with the status codes.

Well, speaking as a client developer, the API is far, far easier for me to understand and write logic against if its authors agree to send back HTTP statuses with their standardized meanings instead of making up their own scheme.

HTTP statuses have no "standardized meanings" at the application level.

You can return a 400 and still return a json payload in the http message body. Maybe is that what the parent is saying?

IIRC cross domain requests are often one of the causes for this style of API design. I remember in older browsers at least anything not in 2XX would be unreadable by the client, so they had no idea what actually went wrong on the frontend.

That's... extremely rare, extremely ancient, and even then was usually only a problem below a certain page length.

I have integrated against many weird B2B APIs and those who always return 200 are actually pretty nice to work with so even if it is a weird choice as an API consumer I do not mind it all, there are much worse things you can do.

I’ve heard the argument as: “HTTP errors for protocol level errors, 200 + json for application level errors”

And honestly it kinda make sense when you think about it that way. “404, wrong url” and “404, id not found” should be different errors.

> “404, wrong url” and “404, id not found” should be different errors

I'd actually argue the opposite, though I can definitely see both sides.

To me, because two systems communicating RESTfully need not know anything about each other, responding to "please give me the resource as this URI" with "there is no resource at that URI" seems perfectly correct. I don't really need to know the specifics of how the remote machine is dealing with my request.

If more detail is required you can always include a message in the request body, which I think should be standard practice for handled errors anyway.

I experienced something similar with a currency value API. Every response was 200 OK with a field containing the actual HTTP error if there was one. I made an issue on their GitHub explaining why that made consumers code messier than it should be and asked if they could fix it. They replied saying sure, but after several months they closed the issue without a fix and then refused to reply further, and then went and did a 360 degree rebrand of the company changing the pricing model and the API itself. I ripped out usage of their garbage API and replaced it with another almost immediately.

Ha, I love it when people make dumb excuses for awful decisions like that. /s

I much prefer colleagues who can say, woah that was dumb thanks for informing me of a better way. Making excuses doesn't help anyone unless one has a valid logical reason they did a certain thing, otherwise I DONT WANNA HEAR IT.

The people who write the API and the people who are tasked to provide support for it are usually not the same. If these are APIs between internal business units, my condolences, no excuse.

> I had to work with an API where the company decided everything should return http code 200 (well, at least all 4XX errors), and give the error code in the JSON response, mixing existing 4XX errors and their own errors.

I've done something like this in the past. There was a (horrible) reason; old versions of Android had terrible built-in HTTP stuff and tended to break on any 'unusual' HTTP responses (for instance, 204), especially where HTTP compression was enabled. By far the safest way to support clunky old Androids turned out be be just return 200 for everything with the real code embedded elsewhere...

Ugh, i'd put a gateway in front of it that transformed the status codes to a 200-response.

Instead of building your api according to the default Android client ( ps. Lookup BFF microservices)

It was a while ago, and we were very cost sensitive.

FWIW, I think the last Android phones with these client issues have probably died by now (it got mostly sorted out in 4.3 or so IIRC); this isn't a current concern.

Just pointing out an alternative that wouldn't break/uglify your api ;)

This isn't the ArcGIS Server API is it?

No this isn't. Without calling out names, the first one is a small localization platform (but seems to be a very prevalent issue in multiple APIs) and the second is an international hosting provider. Both are good enough for my case to overlook those issues, that are nevertheless infuriating.

Man that thing is a mess, isn't it....

I had that when I was dealing with the Withings API. Oh you got a 4XX error? Here is a 200 back with a json payload of {error: 400, message: "Some message"}.

Ugh it was frustrating.

So I wasn't wrong. I fought someone over this and someone else was like 'looks okay to me'...

I think that 200 status code for everything is such a bad practice. I'm surprise the amount of people here that are OK with that.

Slack API does that too

(to their credit, the docs are very complete and clear, even if their API design is questionable)

> decided everything should return 200

Sounds like that decision came from someone who didn’t spend much of their career consuming APIs.

I spent a quite big part of my career consuming APIs and an API which always return 200 is no big deal. The opposite which I have also encountered is much worse, returning successes with 4XX, because some libraries do not like that. Why does the opposite happen? Because sometimes it is not obvious if something is an error or just another return value.

But they are higher ups and should obviously be allowed to make ALL decisions, why listen to some developer who is beneath them. That dev has only spent the last 5 years working with APIs, databases, and web applications, what does he even know, probably nothing? /s

Sounds familiar... ugh