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.

  • magic_lobster_party@fedia.io
    21·
    10 months ago

    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.