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.
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.
403 is a category, not a code. Yes I know they're called http codes but REST calls are more complex than they were in 2001. There are hundreds of reasons you might not be authorized.
Is it insufficient permissions? Authentication required? Blocked by security? Too many users concurrently active?
I'd argue the minimum for modern services is:
403 category
Code for front end error displays
Message as default front end code interpretation
As json usually but if you're all using protobuf, go off King.
I've never heard of using protobuf in an HTTP API... But, I guess that should be fine.
The thing is, it does exists a way to convert grpc protobuf to json one