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.

  • kevincox
    6·
    3 months ago
    HTTP/1.1 403 UNAUTHORIZED
{
  "error": {
    "status": "UNAUTHORIZED",
    "message": "Unauthorized access",
  },
}

    I would separate the status from the HTTP status.

    1. The HTTP status is great for reasonable default behaviours from clients.
    2. The application status can be used for adding more specific errors. (Is the access token expired, is your account blocked, is your organization blocked)

    Even if you don’t need the status now, it is nice to have it if you want to add it in the future.

    You can use a string or an integer as the status code, string is probably a bit more convenient for easy readability.

    The message should be something that could be sent directly to the user, but mostly helpful to developers.