HTTP/1.1 403 UNAUTHORIZED
{
  "error": {
    "status": "UNAUTHORIZED",
    "message": "Unauthorized access",
  },
}

I would separate the status from the HTTP status.

1. The HTTP status is great for reasonable default behaviours from clients.
2. The application status can be used for adding more specific errors. (Is the access token expired, is your account blocked, is your organization blocked)

Even if you don’t need the status now, it is nice to have it if you want to add it in the future.

You can use a string or an integer as the status code, string is probably a bit more convenient for easy readability.

The message should be something that could be sent directly to the user, but mostly helpful to developers.

The status code that gets returned should be the status code of the messenger and not the data. If you want to add a status code about the data, then please do.

If something can return null and empty and it’s valid, that is not a 404. That is a 200.

As far as a 403, the messenger is telling you that you shall not pass. There is no data. 403 is appropriate here. The return response can be anything since 403 is pretty self explanatory, but I would probably return json to be consistent. I would also use the field message. Something like the first one for this use case only.

In other cases where i do get data, I would use data, message, status (optional). But status in the json response would be status about the message.

The documented one. It is hell to work with APIs where only the happy path is documented.

For me it just depends on what I expect. They’re all relatively the same thing. As long as the status code is appropriate (403), it doesn’t matter whether it’s JSON or plaintext. Ideally the API would respect and handle the request header, and return plaintext if you request plaintext.

I think the general rule of thumb is: Keep it Simple, Stupid.

Don’t include fields “just in case”. If you don’t have a use for a field right now, then don’t include it. It’s often easier to add fields than removing.

Avoid having fields that can be derived from other fields. Code “UNAUTHORIZED” can be derived from 403. Having both adds confusion. It adds the question whether the code field be something other than “UNAUTHORIZED” when the response is 403.

Just 403 with empty body is fine. Add message in a JSON in case it’s useful for the user. If the user needs more fields in the future, then it’s easy to expand the JSON.

I like the fourth or the last one since it encourages all other error responses to follow a similar standard. That will allow the client to have a reusable error model and error checking.

I’ve had to use APIs where every response was 200 ok with json, 400 bad request with pain text that said unauthorized, or a 500 error that returned an HTML error page. The worst.

https://www.rfc-editor.org/rfc/rfc9457.html

It’s 401 unauthorized or 403 forbidden, not 403 unauthorized

Have a code, where you can really describe the error; try to use the correct HTTP status (your example doesn’t); don’t ever use status 200 for errors; and finally, have an “error” key set to something somewhere (I’d write the error code to it).

The message is optional.

So, the simplest version would be:

HTTP/1.1 401 POST /endpoint
{
     "error": "UNAUTHORIZED"
}

That clown emoji would make me think the company has alt-right sympathies

The last one is very convenient. As an API consumer you can get all the necessary info from the returned payload, and the 403 will trigger the error path.

Anything but the last one. Don’t duplicate the http code in the body, else you’re now maintaining something you don’t need to maintain.

I’m not a fan of codes that repeat information in the body either, but I think if you had used a different example like “INVALID_BLAH” or something then the message covered what was invalid, then it would be fine. Like someone else said, the error data should be in an object as well, so that you don’t have to use polymorphism to figure out whether it’s an error or not. That also allows partially complete responses, e.g. data returns, along with an error.

A mix between the last one and the previous. The key error should be set in order to indicate the presence of an error, while status and code represents, respectively, the error numerical code and the error type, while the error message is supposed to be concatenated to an human-friendly error text.

I really like the fifth one. So you might always get a surprise message in your response

Respect the Accept header from the client. If they need JSON, send JSON, otherwise don’t.

Repeating an HTTP status code in the body is redundant and error prone. Never do it.

Error codes are great. Ensure to prefix yours and keep them unique.

Error messages can be helpful, but often lead developers to just display them in the frontend, breaking i18n. Some people supply error messages in multiple languages, depending on the Accept-Language header.