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.

  • huginn@feddit.it
    15·
    20 days ago

    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.

    • hexbatch@programming.dev
      1·
      20 days ago

      Yes, the more information and standards in an api response the better. There should be front end messages and developer messages. URL links to documentation are great too. Standards assist automation and testing.

      I understand other viewpoints about maintenance and redundancy, this can cause errors. And the above is too much work for some projects .

      But most api start as a temporary or one person project. It’s tempting to be terse and cool with responses . Even more tempting is this is a great cost cutter to not have overly detailed responses.

      However

      It’s much easier to add in more data to responses now than later. And a future you years later, or strangers who use it , will be grateful. It may be the thing that allows an api to be popular, rather than people use it despite the api