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.
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 would actually encourage error responses be in JSON if your 200 responses are JSON. Some clients are apt to always convert the body to JSON so it could avoid an exception on the client side not to throw a curveball.
To your point it's most important that the content and Content-Type header match.
If any client app is blindly converting body to JSON without checking (at the very least) content type and size, they deserve what they get.
If you want to make it part of your API spec to always return JSON that's one thing, but don't do it to make up for poorly written clients. There's no end of ways in which clients can fail. Sticking to a clear spec is the only way to preserve your sanity.