Personally I tend to do it like 1, also in my company we do that (though not elixir).

Our naming is a bit different though.

We tend to do it more like {"status": "ok", "data": …}/{"status": "error", "reason": …}. "reason" can, depending on how well defined the API is, be a plain string for human consumption or an object containing a numeric error code, a severity and free form “args”. But then always a human readable string is provided as well.

{
  "status": "error",
  "reason": {
    "code": 404,
    "description": "Resource 'foo' not found",
    "args": { "resource": "foo" }
  }
}

I think that a good REST API should indicate success/failure via the response status code. So returning 20x when a request has in fact failed (even if it was due to a business error) would be IMO misleading. If HTTP status codes are used, then success/failure can be distinguished on the client side by looking into the response status.

I do agree that HTTP error codes are probably too coarse grained for business errors, so providing additional context as a payload is fine.

This depends on the transports which have to be supported. For example, at Aircloak besides HTTP, we also support PostgreSQL protocol (we pretend to be a PostgreSQL database). Error reporting in that protocol has to be done in a particular way, so it’s still transport specific. Having the same shape of response sent via HTTP and via PostgreSQL protocol wouldn’t work for us.

Because errors in your application do not map to HTTP status codes very well.

My example with the resource not found was just an example. But if the user provided some value out of bounds, what HTTP status code would you use?

Also, if you say 404 is resource not found, how do you distinguish from the HTTP resource not beeing found vs. some resource not found which you specified in your arguments to the request?