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.
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.
There may be a need for additional information, there just isn’t any in these responses. Using a basic JSON schema like the Problem Details RFC provides a standard way to add that information if necessary. Error codes are also often too general to have an application specific meaning. For example, is a “400 bad request” response caused by a malformed payload, a syntactically valid but semantically invalid payload, or what? Hence you put some data in the response body.
A plain 400 without explanation is definitely not great UX. But for something like 403, not specifying the error may be intentional for security reasons.
I know of some people that never use 403, but instead opt for 404 for security reasons. 403 implies that there is something they could have access to, but don’t.
I think in some situations that this can be valid, but it shouldn’t be a crux.
404 is definitely also used sometimes for hiding stuff that shouldn’t be seen, but 403 may still be appropriate for various stuff where there is nothing to hide. With 404 you probably also never want to give any explanation or error message.