I prefer simplicity and using the first example but I'd be happy to hear other options. Here's a few examples:
HTTP/1.1 403 POST /endpoint
{ "message": "Unauthorized access" }
HTTP/1.1 403 POST /endpoint
Unauthorized access (no json)
HTTP/1.1 403 POST /endpoint
{ "error": "Unauthorized access" }
HTTP/1.1 403 POST /endpoint
{
"code": "UNAUTHORIZED",
"message": "Unauthorized access",
}
HTTP/1.1 200 (🤡) POST /endpoint
{
"error": true,
"message": "Unauthorized access",
}
HTTP/1.1 403 POST /endpoint
{
"status": 403,
"code": "UNAUTHORIZED",
"message": "Unauthorized access",
}
Or your own example.
Yes, the more information and standards in an api response the better. There should be front end messages and developer messages. URL links to documentation are great too. Standards assist automation and testing.
I understand other viewpoints about maintenance and redundancy, this can cause errors. And the above is too much work for some projects .
But most api start as a temporary or one person project. It’s tempting to be terse and cool with responses . Even more tempting is this is a great cost cutter to not have overly detailed responses.
However
It’s much easier to add in more data to responses now than later. And a future you years later, or strangers who use it , will be grateful. It may be the thing that allows an api to be popular, rather than people use it despite the api