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.

Giving back a 200 for an error always makes me bristle. Return correct codes people. “But the request to the web server was successful!”

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

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.

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.

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?

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

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.

I don't have a response to share but I always lose my mind when I see AWS error messages, especially when using bazillion layers like CDK for Terraform, executed from the shell script that runs a python script in the CI/CD pipeline.

One of the issues I will never forget was the debugging of permission issue. Dev reported an issue, something like "cannot access the SQS queue from a recently deployed script". The error message was like "cannot access the queue due to missing policy in assumed role" (or something similar). So, I have checked the python script and related policies - all good. Next I've moved to a shell script, still no luck. After that I went through the CDK files, no issues. I was about to involve the AWS support when it turned out that the queue name has been changed manually in the AWS console. AWS, instead of point out that the queue is missing, raised an error about missing access permissions...

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

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.

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.

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
}

When consuming APIs you often want JSON in successful scenario. Which means, if you also have JSON in unsuccessful scenario it's a bit more uniform, because you don't have to deal with JSON in one case and plaintext response in other. Also, it sometimes can be useful to have additional details there like server's stacktrace or some identifiers that help troubleshoot complex issues.

just 403 and leave the body empty

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.

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.

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.

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.

Message straight on the body is the worst possible response for an error here, it is bad design to straight up show the error from the back end to the user, usually it needs translation and/or adaptation due to message size on the front-end to show properly, and applying those on top of a message will make it stop working as soon as anyone in the backend decide to change a dot or comma anywhere. It is a bad idea to let the backend make direct impact in the front when you can because backend devs won't even know what impact they are causing until later in testing and it will be harder to trace back and fix.

IMO you need at least a json with code and message, the front will ignore the message for everything but testing and use the code to match a translation file that will get the proper message, making it easy to translate and change as needed without having to rebuild the whole backend along with front changes. You may also have an extra parameter there in some cases when you want to return where more specifically the error occurred or an array of errors. Status usually not needed as you can get those from the http code itself.

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

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

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.

GitHub has OpenAPI specification. Latest version is 3.1, I think.

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?

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 really like the fifth one. So you might always get a surprise message in your response

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.