Programming

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

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

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.

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'm a data engineer, and have seen an ungodly ammount of 200-but-actually-no-stuff-is-broken errors and it's the bane of my life!

We have generic code to handle pulling in api data, and transforming it. It's obviously check the status code, but any time an API implements this we have to choose between:

• having code fail wierdly further down the line because can't parse the status
• adding in some kind of insane if not response.ok or "actually no there's an error really" in response.content logic

Every time you ignore protocols and invent your own, you are making everyone sad.

Will take recommendations of support groups I can join for victims of terrible apis.

#4 for me.

Proper HTTP Status code for semantic identification. Duplicating that in the response body would be silly.

User-friendly "message" value for the lazy, who just wanna toss that up to the user. Also, ideally, this would be what a dev looks at in logs for troubelshooting.

Tightly-controlled unqiue identifier "code" for the error, allowing consumers to build their own contextual error handling or reporting on top of this system. Also, allows for more-detailed types of errors to be identified and given specific handling and recovery logic, beyond just the status code. Like, sure, there's probably not gonna be multiple sub-types of 403 error, but there may be a bunch of different useful sub-types for a 400 on a form submission.

1 or 3; maybe 4.

With several assumptions made, ultimately, they're asking for json, and we should still return json, but what that looks like is up to you. It should be static enough that the person on the other end can write:

If json.grtnode(error) == "unauthorized access"
Do stuff

Ifnyour going to be changing the text with some regularity to contain relevant information for the error (eg, an item ID, that is now invalid), then consider a code/text and additional fields.

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?

1, 3, 4 are good but out of laziness I'd personally use the first.

At a previous job we had an unholy combination of the last two:

HTTP/1.1 200 POST /endpoint 
{
  "data": null,
  "errors": ["403", "unauthorized"],
  "success": false
}

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.

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?

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 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.

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.

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

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.

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

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.

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