>> Bottom line - your server should always return HTTP status 200 and a separate API error response.
That is a very absolute statement from a pragmatic guy, asking people to concede viewpoints other than their own :)
I'd be interested in learning how status codes other than 200 cause problems at scale though?
"Hi, this is the application and the object/document/whatever you are looking for was not found"
with
"Hi, this is the server and the api endpoint was not found"
An API I use returns a standard apache 404 error page when the item you are looking up doesn't exist. If the API endpoint was renamed my code that consumes it wouldn't have any idea anything was wrong.
I didn't mean to imply that HTTP status codes could stand alone as error messages, so for a 404 error I'd also respond with more data, to help the user identify the issue.
Also note that not all APIs will be used be developers. Often it's someone less proficient with programming, and you can't rely on them to check the content of the return message. Help them help themselves by making curl (or whatever) bitch when there is an error.
It takes a bit more work to design an API that works over multiple transports, but a good framework, such as Servicestack.net if your in .Net land, mostly does it for you. By advocating 200 for all responses you're basically reverting to SOAP and WCF (Windows Communication Foundation).
Each to his own though, and for internal stuff, it might make a lot more sense.