Some of the fault for this lies with client libraries. Many, including popular ones[1], either don't provide a way to get the body of error responses at all, or make it particularly cumbersome to do so. For example, success bodies might be parsed automatically by registering the right parser for the content type, but to parse an error response you need to manually instantiate a parser and deserialise the body. Until error responses are first-class objects in client http libraries, devs will continue being lazy.

[1] Not to pick on retrofit -- it is generally awesome -- but http://square.github.io/retrofit/2.x/retrofit/retrofit2/Resp...

omg I saw this once.

The status code was 200 but the HTTP body was literally "403: Forbidden". On an endpoint that was supposed to return XML .

I guess they just read the spec and assumed "the API returns a '403: Forbidden' " meant this.

All my clients do that. They literally think that REST means "JSON over HTTP" and don't bother with anything else :(

I wish I only saw this once. This is my life. I integrate with 3rd party APIs for a living...what I've learned is that everyone's 'REST' API is terrible in one way or another.

Microsoft Silverlight (RIP) only exposed 200 and 404 status codes to the application when using the browser's HTTP stack, presumably due to some API limitation somewhere along the line.

See the Remarks section: https://msdn.microsoft.com/en-us/library/system.net.httpstat...

Other client plugins may have similar issues.

I remember reading that ISP's and browsers can do interesting things to non-2xx responses. In that case applications do not even have a chance to handle the error. IIRC Facebook's API does this because they encountered problems with mobile browsers deciding to do weird things with non-2xx responses.

No, this hasn't ever been a thing. This is just stupidity on the side of the developers.

You may be thinking about DNS hijacking by ISPS, but not non-200 issues. There are bound to be some terrible apps out there that respond badly as well, but that's really no excuse.

I am not talking about the app I am talking about the environment the app is running in. Of course there are crappy apps (I've made a bunch of them!) I remember IIS doing funky things with non-200 return codes. 5xx codes would have some default handler. I am certain this was an issue with configuration and a dysfunctional development process. In the shop I was in, in the mid 2000's, we the devs didn't have direct access to the web server and having the IT guys make any update took on the order of weeks. Instead of fixing the IIS config we just returned 2xx and handled the error in the app layer. We also had a couple SOAP(shudder) services that always returned code 200 with error codes in the response XML body. Much of our app code used this pattern for consistency. We also would deploy our services on various other web servers we didn't have full control over so it was just easier to use this pattern.

This is how GCP tells you access to a resource is forbidden. I wrote an Ansible dynamic inventory script and have had to deal with this behaviour.

For example:

Response 403

{'error': {'errors': [{'domain': 'global', 'reason': 'forbidden', 'message': "Required 'compute.instances.list' permission for 'projects/golden-sandbox-162219'"}], 'code': 403, 'message': "Required 'compute.instances.list' permission for 'projects/golden-sandbox-162219'"}}

A quick glance at history of HTTP can explain this without incompetence. HTTP is fundamental to the world wide web and existed from the beginning in 1989. Fielding's dissertation introduced the idea of REST in 2000. And REST became part of mainstream client libraries in what, 2010? So there's a 20 year period during which code was written against HTTP libraries which were not idiomatic from a REST perspective. Returning status codes in the response body is a common workaround for compatibility with code written in this 20 year window.

Status codes aren't something introduced by REST, they've been a standard part of HTTP since HTTP 1.0. They've been in widespread use for decades. People use 200 for errors for a few reasons, but it's not because HTTP 0.9 didn't have them.

I started programming professionaly in 2005 and I can assure you that back then, outside of the browsers, people really didn't know or understand response codes.

There's a load of early, popular, Stack Overflow questions that revolve around what status to return when, and how to actually return those codes in your language. For example, in ASP.Net/IIS it was actually quite hard to stop IIS 6 (?) from swallowing your 500 xml response and serving a custom html error page. If I remember correctly some browsers didn't support PUT properly either.

So while you are technically correct, the codes were in use, you are historically wrong, few people outside of a small community understood their use.

I remember this article from the first time around, when people were really getting into REST and there was a fierce debate about strict REST Vs RESTful. In reality RESTful has mainly won and this article was on the wrong side of history.

> I started programming professionaly in 2005 and I can assure you that back then, outside of the browsers, people really didn't know or understand response codes.

> So while you are technically correct, the codes were in use, you are historically wrong, few people outside of a small community understood their use.

I started in the late 90s, and even back then they were commonly used. They weren't just well understood by developers, but they were actually in non-developer's lexicons as well. If you asked the typical geek back then what a 404 was, chances are they'd be able to tell you that it meant something was missing. So I don't agree with you that they were understood by "few people outside of a small community" at all. Using status codes has been standard practice for decades. Maybe it took a couple of years at the beginning of your career for you to notice them, but there simply wasn't this time period of decades when they weren't in use until REST came along.

Given that ajax was only added to browsers in 1999 and AJAX didn't really catch on seriously until 2003/2004ish, what you're claiming is at odds, again, with actual history.

404s are a different matter because you'd get 404 pages, so it's not at all an argument to support your position. It doesn't mean developers understood what to return from an ajax call, or that they understood HTTP verbs.

I'll remind you again that it was actually fairly hard to return the correct codes from a lot of frameworks, so objective facts are at odds with your recollection of events.

I stick by my assertion that the vast majority of web developers in our industry didn't really understand http until the latter half of the 2000s. I also specifically remember presentations to all our developers both junior and senior of how browser caching worked, which to most developers at the time was a bit of a mystery, and the correct headers to return to control it.

Here are some examples from 2008 of developers on SO discussing things which seem obvious today:

http://stackoverflow.com/questions/165779/are-the-put-delete... http://stackoverflow.com/questions/165720/how-to-debug-restf...

> Given that ajax was only added to browsers in 1999 and AJAX didn't really catch on seriously until 2003/2004ish, what you're claiming is at odds, again, with actual history.

Ajax is not the only way to access a web service.

> 404s are a different matter because you'd get 404 pages

…which are returned with a status code of 404. That's where the name comes from. Non-200 status codes were ubiquitous even back then.

> It doesn't mean developers understood what to return from an ajax call, or that they understood HTTP verbs.

Ajax is irrelevant and we're talking about status codes, not verbs.

> I'll remind you again that it was actually fairly hard to return the correct codes from a lot of frameworks, so objective facts are at odds with your recollection of events.

Perhaps the technology _you_ were using made it difficult, but it certainly wasn't the general case. PHP, classic ASP, mod\_perl, mod\_python, CGI scripts… they could all respond with non-200 status codes easily. Which ones are you thinking of that made it difficult?

> Here are some examples from 2008 of developers on SO discussing things which seem obvious today:

Come on man, clueless questions get asked about extremely well established things on Stack Overflow every single day. That doesn't mean that those concepts are suddenly no longer well understood, it just means that the person asking is a beginner. And neither of those questions mentioned status codes at all!

I think IIS7's 5xx idiocy was more driven by misguided security concerns. Same as HTTP.sys requiring you to get permission to listen on a port versus not needing any permission if you just open a socket. Or same reason telnet.exe doesn't get installed by default.

The endpoints in question are not typically used by humans driving a browser, so these objections don't seem applicable.

yeah but there are bits in the ~2000 era backend request pipeline that don't understand anything but 200 or do weird things, embedding response code in 200 body lets us tunnel through whatever weird legacy shit

> there are bits in the ~2000 era backend request pipeline that don't understand anything but 200

There's badly written buggy software from any time period doing all sorts of crazy shit, but only accepting 200 certainly wasn't the norm, or even commonplace back then.

Nor was it even just idiomatic HTTP. Using the proper HTTP status or verbs for instance is not REST, just caring about the HTTP spec.

you're right, a little deeper digging and i learned that in 1989 http only had GET! I dont think verbs came until '96

I've seen plenty of this is in code written in the past 5 years, some within the last year or two.

It comes from SOAP, which is supposed to be "protocol independent" so you would return statuses inside of the envelope section of the XML.

This was a common workaround, so that customers don't get nervous, as some browsers showed an increasing number in a red circle at the top right. (i.e. the number of JavaScript errors)

Wait...

You gotten a response that's HTTP 200, but the JSON itself contained something like "code: 403"?

Well, now I know what I'm going to do if I ever really hate my coworkers/company.

I've seen that, and also status = 500 with the body { ok: false, status: 404 }

The codebase I'm working on currently has that and more.

This used to be necessary with flash clients, as they wouldn't get the response body if the response had an error status. I can't think of a reason to do something like this nowadays that flash is dead.

That leads to cleaner code for the frontend frameworks, better interoperability and simpler debugging. Web server error codes are for web server failures and application level errors are communicated via a 200, properly. I run in to this all the time and once we adopted it (for all our APIs), life has been better for customers and our internal teams.

> "application level errors are communicated via a 200, properly"

Wiki:

   2xx Success
   This class of status codes indicates the action requested by the client was received, 
   understood, accepted, and processed successfully

RFC 2616:

   10.2.1 200 OK
   The request has succeeded

Not really "proper" to use it that way, but if it works for you and your users I guess go for it. Also, I highly disagree with the rest of it (cleaner code, better interoperability, simpler debugging), but those are matters of opinion so there's no point in arguing them.

> client was received, understood, accepted, and processed successfully

How is this not processed successfully? The request was processed successfully by the webserver ... and the error was handled by the application, so you can reliably say it was processed successfully at that level, down to the CPU. Narrow interpretation to fit a narrative has no technical merit. That being said, standards are set with certain models in mind and are imperfect almost uniformly, so I don't put too much stock in adherence to what someone imagined or put through committee at some point. I do try to find the best way to iterate reliably with least astonishing abstractions and predictable interfaces. I reason about it in the terms of the standard and it serves my teams.

> Web server error codes are for web server failures and application level errors are communicated via a 200, properly.

No, expressly in the HTTP spec, 5xx error codes are server errors. 4xx codes are all different kinds of application-level (usually resource-specific) errors.

2xx codes are full-stack success codes.

> Web server error codes are for web server failures and application level errors are communicated via a 200, properly.

I guess google, facebook, microsoft and all the others are doing it wrong then? Or Improperly according to you? Because they do not respond with a 200 on application level errors in their APIs.

> I guess

They made a choice to treat multiple applications as one. That's not what I would prefer and is less useful in my opinion. There are some CDNs and payment processors that are in operation, that use the 200 error response, so I tried it. I think it's clearly superior. YMMV

The needs and use case for Google, Microsoft, and Facebook are radically different than anyone else. No developer should imitate them blindly because, chances are, the conditions you are working in do not match the big four. There is no ideal way of coding, instead, you match your style to what is needed. I wish more people understood that.

It's an error code, not a massively distributed system. There's no reason why the solution for the "big four" should be different than for anyone else. Especially since their APIs are designed to be used by everyone else.

You can blame old browsers for this. In the old days if you returned a non 200 the browser could die in all sorts of interesting ways. Heaven forbid if you try and use any verb other than GET or PUSH, it probably turns the fan off your computer to try and start a fire or something.

>You can blame old browsers for this. In the old days if you returned a non 200 the browser could die in all sorts of interesting ways.

No, they really didn't. And I've started with Mosaic...

Do you mean POST?

Also, these days, I think the blame is more likely lazy devs, poorly complying frameworks, or compromises to make things easier for some frontend library.

Who on Earth is using a browser so old that this might actually happen?