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.

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

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.

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.

Anything except the 2nd to last one, which is, unfortunately, mandated by my employer’s internal code style guidelines. 🫠

JSON Problem Details

https://datatracker.ietf.org/doc/html/rfc9457

• It has a specification, so a consumer of the API can immediately know what to expect.
• It has a content type, so a client sdk can intelligently handle the response.
• It supports commonly needed members which are a superset of all of the above JSON examples, including type for code and repeating the http status code in the body if desired.
• It is extensible if needed.
• It has been defined since at least 2016.

This specification’s aim is to define common error formats for applications that need one so that they aren’t required to define their own …

So why aren’t you using problem details?

There are competing interests here: normal consumers and script kiddies. If I build an API that follows good design, RFCs, pretty specs, all of that, my normal users have a very good time. Since script kiddies brute force off examples from those areas, so do they. If I return 200s for everything without a response body unless authenticated and doing something legit, I can defeat a huge majority of script kiddies (really leaving denial of service). When I worked in video games and healthcare, this was a very good idea to do because an educated API consumer and a sufficiently advanced attacker both have no trouble while the very small amount of gate keeping locks out a ton of annoying traffic. Outside of these high traffic domains, normal design is usually fine unless you catch someone’s attention.

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.

Don’t use JSON for the response unless you include the response header to specify it’s application/json. You’re better off with regular plaintext unless the request header Accept asked for JSON and you respond with the right header.

That also means you can send a response based on what the request asked for.

403 Forbidden (not Unauthorized) is usually enough most of the time. Most of those errors are not meant for consumption by an application because it’s rare for 4xx codes to have a contract. They tend to go to a log and output for human readers later, so I’d lean on text as default.

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.

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.

My favourite is when every error is an HTTP Bad Request with no body. Absolutely wonderful to use those APIs

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.

Is the last one real? Has any sane dev made something like that monstrosity? It’s not like the others are any better, but who would ever think of doing the last one and why?

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.