I like using Problem detials

It’s fully supported by the .net server pretty much out the box and just seems nice to stick to a standard where possible.

I like the last one, I think having the status code in the body could help clarify where the error is coming from when traversing a reverse proxy.

since none of your examples add anything of value in the body: a plain old 403 is enough.

response bodies for 400 responses are more interesting, since you can often tell why a request was bad and the client can use that information to communicate to the user what went wrong.

best error code remains 418, though.

1 or 4 but wrapped in a top level error object. It’s usually best to not use the top level namespace because then you can’t add meta details about the request easily later without changing the original response schema.

Codes are great but I’m usually too lazy to introduce them right away, so I instead have message (which is guaranteed to come back) and context, which is any JSON object and doesn’t adhere to a guaranteed structure. Another poster pointed out that code is way easier for localization since you are probably not localizing your message.

The HTTP status code is generally sufficient to describe what happened without having to catalogue every error with a unique “code”. A context blob is useful for dumping validation errors or any other details about the error that a human could at least rely on for help.

Putting the status code on the body seems helpful but is actually useless, since the only place you can assume it’s always provided is on the response itself and not the body.

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

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.

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

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.

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.

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

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.

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"
}

A simple error code is sufficient in all of these cases. The error provided gives no additional information. There is no need for a body for these responses.

Of those options I’m going with the last one. Because you have the standard error number right there but I’m assuming that it’s a customer response so the message could be modified to have something useful in it.

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.