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.

  • @elrikEnglish
    18•3 months ago

    JSON Problem Details

    https://datatracker.ietf.org/doc/html/rfc9457

    • It has a specification, so a consumer of the API can immediately know what to expect.
    • It has a content type, so a client sdk can intelligently handle the response.
    • It supports commonly needed members which are a superset of all of the above JSON examples, including type for code and repeating the http status code in the body if desired.
    • It is extensible if needed.
    • It has been defined since at least 2016.

    This specification’s aim is to define common error formats for applications that need one so that they aren’t required to define their own …

    So why aren’t you using problem details?