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.

  • ramble81@lemm.ee
    0·
    16 days ago

    Giving back a 200 for an error always makes me bristle. Return correct codes people. “But the request to the web server was successful!”

    • gencha@lemm.ee
      0·
      15 days ago

      I don’t necessarily disagree, but I have spent considerable time on this subject and can see merit in decoupling your own error signaling from the HTTP layer.

      No matter how you design your API, if you’re passing through additional layers, like load balancers and CDNs, you no longer have full control over all responses your clients receive. At this point it may be viable to always signal a successful backend connection with a 200, even if the process resulted in a failure.

      Going further, your API may include partial success scenarios, think batch processing, then the result could be a mix of success and failure that doesn’t translate to HTTP status.

      You could even argue that there is really no reason to couple your API so tightly with a concept of the transport layer it uses.

    • FizzyOrange@programming.dev
      0·
      16 days ago

      I use this big expensive simulator called Questa, and if there’s an error during the simulation it prints Errors: 1, Warnings: 0 and then exits with EXIT_SUCCESS (0)! I tried to convince them that this is wrong but they’re like “but it successfully simulated the error”. 🤦🏻‍♂️

      We end up parsing the output which is very dumb but also seems to be industry standard in the silicon industry unfortunately (hardware people are not very good at software engineering).

      • Dark Arc@social.packetloss.ggEnglish
        0·
        16 days ago

        That’s when you use different exit codes. 1 for failure during simulation, 2 for simulation failed.

        Shame they wouldn’t listen.

    • OneCardboardBox@lemmy.sdf.orgEnglish
      0·
      16 days ago

      I worked on a product that was only allowed to return 200 OK, no matter what.

      Apparently some early and wealthy customer was too lazy to check error codes in the response, so we had to return 200 or else their site broke. Then we’d get emails from other customers complaining that our response codes were wrong.

  • Tellore@lemmy.worldEnglish
    0·
    16 days ago

    When consuming APIs you often want JSON in successful scenario. Which means, if you also have JSON in unsuccessful scenario it’s a bit more uniform, because you don’t have to deal with JSON in one case and plaintext response in other. Also, it sometimes can be useful to have additional details there like server’s stacktrace or some identifiers that help troubleshoot complex issues.

  • Dunstabzugshaubitze@feddit.org
    0·
    16 days ago

    since none of your examples add anything of value in the body: a plain old 403 is enough.

    response bodies for 400 responses are more interesting, since you can often tell why a request was bad and the client can use that information to communicate to the user what went wrong.

    best error code remains 418, though.

    • epyon22@programming.dev
      0·
      16 days ago

      I was annoyed that the one time I wanted to use 418 as a filler Dotnets http library didn’t support returning it.

  • magic_lobster_party@fedia.io
    0·
    16 days 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.

    • huginn@feddit.it
      0·
      16 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.

      • Lysergid@lemmy.ml
        0·
        16 days ago

        REST calls are same as in 2001. There is no REST 2.0 or REST 2024. Because REST is architecture guideline. It’s just more data sent over it today. HTTP code IS code. Why your system issued it is implementation detail and have nothing to do with resource representation. Examples you provided are not 403. “Too many users active” does not exist in REST because REST is stateless, closest you can get is “too many requests” - 429. Insufficient permissions is 401. I don’t even know what is “blocked by security” but sounds like 401 too. Regardless, you should not provide any details on 401 or 403 to client as it is security concern. No serious app will tell you “password is wrong” or “user does not exist”. Maximum what client should hope for is input validation errors in 400.

        For those with “internal tool, I don’t care” argument - you either do not know what security in depth is or you don’t have 403 or 401 scenario in the system in the first place.

        Now hear me out, you all can do whatever you want or need with your API. Have state, respond with images instead of error codes, whatever, but calling it REST is wrong by definition

        • huginn@feddit.it
          0·
          16 days ago

          Theory is fine but in the real world I’ve never used a REST API that adhered to the stateless standard, but everyone will still call it REST. Regardless of if you want it or not REST is no longer the same as it’s original definition, the same way nobody pronounces gif as “jif” unless they’re being deliberately transgressive.

          403 can be thrown for all of those reasons - I just grabbed that from Wikipedia because I was too lazy to dig into our prod code to actually map out specifics.

          Looking at production code I see 13 different variations on 422, 2 different variations of 429…

          • Lysergid@lemmy.ml
            0·
            16 days ago

            “Stateless” is not what “I” want, it is part of definition of REST.

            Can do != what spec says you should do. You can also send clown version from the post but don’t be surprised people will find it… funny

            Again, I’m not telling you are doing wrong. I’m telling you are mixing REST and RESTful web services

  • redline23@lemmy.world
    0·
    16 days ago

    I like the fourth or the last one since it encourages all other error responses to follow a similar standard. That will allow the client to have a reusable error model and error checking.

    I’ve had to use APIs where every response was 200 ok with json, 400 bad request with pain text that said unauthorized, or a 500 error that returned an HTML error page. The worst.

  • fart_pickle@lemmy.world
    0·
    16 days ago

    I don’t have a response to share but I always lose my mind when I see AWS error messages, especially when using bazillion layers like CDK for Terraform, executed from the shell script that runs a python script in the CI/CD pipeline.

    One of the issues I will never forget was the debugging of permission issue. Dev reported an issue, something like “cannot access the SQS queue from a recently deployed script”. The error message was like “cannot access the queue due to missing policy in assumed role” (or something similar). So, I have checked the python script and related policies - all good. Next I’ve moved to a shell script, still no luck. After that I went through the CDK files, no issues. I was about to involve the AWS support when it turned out that the queue name has been changed manually in the AWS console. AWS, instead of point out that the queue is missing, raised an error about missing access permissions…

  • Tanoh@lemmy.world
    0·
    16 days ago

    The clown, but flipped with a success field. If it is true then command succeeded, if it false something was wrong and there should be an error field as well.

    HTTP codes should be used for the actual transport, not shoe-horned to fit the data. I know not everyone will agree with this, but we don’t have to.

    • bitfucker@programming.dev
      0·
      16 days ago

      The transport is usually TCP/IP tho. But nowadays QUIC is trying to make it UDP. HTTP is specifically an Application Layer Protocol from OSI model

  • DaniloT@lemmy.world
    0·
    16 days ago

    Message straight on the body is the worst possible response for an error here, it is bad design to straight up show the error from the back end to the user, usually it needs translation and/or adaptation due to message size on the front-end to show properly, and applying those on top of a message will make it stop working as soon as anyone in the backend decide to change a dot or comma anywhere. It is a bad idea to let the backend make direct impact in the front when you can because backend devs won’t even know what impact they are causing until later in testing and it will be harder to trace back and fix.

    IMO you need at least a json with code and message, the front will ignore the message for everything but testing and use the code to match a translation file that will get the proper message, making it easy to translate and change as needed without having to rebuild the whole backend along with front changes. You may also have an extra parameter there in some cases when you want to return where more specifically the error occurred or an array of errors. Status usually not needed as you can get those from the http code itself.

      • DaniloT@lemmy.world
        0·
        16 days ago

        I see, but the first example option having no code still makes it harder to translate and show the user, so my vote is for the option with a code and message in the json.

  • gencha@lemm.ee
    0·
    16 days ago

    Respect the Accept header from the client. If they need JSON, send JSON, otherwise don’t.

    Repeating an HTTP status code in the body is redundant and error prone. Never do it.

    Error codes are great. Ensure to prefix yours and keep them unique.

    Error messages can be helpful, but often lead developers to just display them in the frontend, breaking i18n. Some people supply error messages in multiple languages, depending on the Accept-Language header.

    • pe1uca@lemmy.pe1uca.dev
      0·
      16 days ago

      but often lead developers to just display them in the frontend

      Oh boy I feel this one.
      My API is meant for scripting (i.e. it’s for developers and the errors are for developers), but the UI team uses it and they just straight display the error from their HTTP request for none technical people which might also not get to know all the parameters actually needed for the request.
      And even when the error is in fact in my code, and I sent all the data I need to debug and replicate the error, the users can’t tell me because the UI truncates the response, so the user only sees something like Error in pe1uca's API: {"error":"bad request","message":"Your request has an error, please check th... (truncated). So the message gets truncated and the link to the documentation is also never shown .-.

    • FizzyOrange@programming.dev
      0·
      16 days ago

      To be fair if it’s an exceptional error message (i.e. database timeout; not incorrect password) I don’t think i18n matters that much. Most people will just be googling the error message anyway, and if not it should be rare enough that using Google translate isn’t an issue.

      • azertyfun@sh.itjust.works
        0·
        15 days ago

        If anything i18n makes things way worse for everyone. Ever tried to diagnose a semi-obscure Windows or Android error on a non-English locale? Pretty sure that’s one of the activities in the inner circles of Hell. Bonus points if the error message is obviously machine-translated and therefore semantically meaningless.

        Unique error codes fix this if they remain visible to the user, which they usually don’t because Mr Project Manager thinks it looks untidy.

      • gencha@lemm.ee
        0·
        15 days ago

        Depends on the product. It’s just something to think about when signaling errors. There is information for the API client developer, there is information for the client code, and there’s information for the user of the client. Remembering these distinct concerns, and providing distinct solutions, helps. I don’t think there is a single approach that is always correct.

  • thesmokingman@programming.dev
    0·
    16 days ago

    There are competing interests here: normal consumers and script kiddies. If I build an API that follows good design, RFCs, pretty specs, all of that, my normal users have a very good time. Since script kiddies brute force off examples from those areas, so do they. If I return 200s for everything without a response body unless authenticated and doing something legit, I can defeat a huge majority of script kiddies (really leaving denial of service). When I worked in video games and healthcare, this was a very good idea to do because an educated API consumer and a sufficiently advanced attacker both have no trouble while the very small amount of gate keeping locks out a ton of annoying traffic. Outside of these high traffic domains, normal design is usually fine unless you catch someone’s attention.

    • iso@lemy.lolOP
      0·
      16 days ago

      Looks like they’re recommending object of error code (number) and message.

  • noride@lemm.ee
    0·
    16 days ago

    I like the last one, I think having the status code in the body could help clarify where the error is coming from when traversing a reverse proxy.