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.

  • gencha@lemm.ee
    link
    fedilink
    arrow-up
    94
    ·
    3 months 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
      link
      fedilink
      arrow-up
      6
      ·
      3 months 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
      link
      fedilink
      arrow-up
      5
      ·
      3 months 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
        link
        fedilink
        arrow-up
        8
        ·
        3 months 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
        link
        fedilink
        arrow-up
        2
        ·
        3 months 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.

  • ramble81@lemm.ee
    link
    fedilink
    arrow-up
    67
    ·
    3 months 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!”

    • FizzyOrange@programming.dev
      link
      fedilink
      arrow-up
      16
      ·
      3 months 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.gg
        link
        fedilink
        English
        arrow-up
        11
        ·
        edit-2
        3 months ago

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

        Shame they wouldn’t listen.

        • fuzzzerd@programming.dev
          link
          fedilink
          English
          arrow-up
          1
          ·
          3 months ago

          I generally agree, but with robocopy they went too far with this, because the status code doesn’t work the way you expect, and you’ve got to script around it.

    • OneCardboardBox@lemmy.sdf.org
      link
      fedilink
      English
      arrow-up
      4
      ·
      3 months 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.

    • gencha@lemm.ee
      link
      fedilink
      arrow-up
      3
      ·
      3 months 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.

    • lemmyvore@feddit.nl
      link
      fedilink
      English
      arrow-up
      2
      ·
      3 months ago

      You should consider if you really want to integrate your application super tightly with the HTTP protocol.

      Will it always be used exclusively over a REST-ful HTTP API that you control, and it has exactly one hop to the client, or passes through hops that can be trusted to never alter the HTTP metadata significantly? In that case you can afford to make HTTP codes semantically relevant for your app.

      But maybe you need to pass data through multiple different types of layers and different mechanisms (socket protocols, pub-sub, file storage etc.) In that case you want all your semantics to be independent from any form of transport.

    • flashgnash@lemm.ee
      link
      fedilink
      arrow-up
      1
      ·
      3 months ago

      It’s usually such an easy thing to do as well, in all the web frameworks I’ve used it’s literally a case of changing Ok to Forbidden, 200 to 403 or something very similar

  • houseofleft@slrpnk.net
    link
    fedilink
    English
    arrow-up
    23
    ·
    edit-2
    3 months ago

    I’m a data engineer, and have seen an ungodly ammount of 200-but-actually-no-stuff-is-broken errors and it’s the bane of my life!

    We have generic code to handle pulling in api data, and transforming it. It’s obviously check the status code, but any time an API implements this we have to choose between:

    • having code fail wierdly further down the line because can’t parse the status
    • adding in some kind of insane if not response.ok or "actually no there's an error really" in response.content logic

    Every time you ignore protocols and invent your own, you are making everyone sad.

    Will take recommendations of support groups I can join for victims of terrible apis.

  • magic_lobster_party@fedia.io
    link
    fedilink
    arrow-up
    22
    ·
    3 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.

    • huginn@feddit.it
      link
      fedilink
      arrow-up
      15
      ·
      3 months 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
        link
        fedilink
        arrow-up
        1
        ·
        3 months 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

      • Lysergid@lemmy.ml
        link
        fedilink
        arrow-up
        1
        arrow-down
        3
        ·
        edit-2
        3 months 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
          link
          fedilink
          arrow-up
          2
          ·
          3 months 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…

            • huginn@feddit.it
              link
              fedilink
              arrow-up
              1
              ·
              3 months ago

              You missed the point:

              The original creator of a thing does not control the current usage.

              It’s analogous.

          • Lysergid@lemmy.ml
            link
            fedilink
            arrow-up
            1
            ·
            3 months 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

  • elrik@lemmy.world
    link
    fedilink
    English
    arrow-up
    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?

    • iso@lemy.lolOP
      link
      fedilink
      arrow-up
      6
      arrow-down
      1
      ·
      3 months ago

      You’re right, I was just giving an example though.

    • sus@programming.dev
      link
      fedilink
      arrow-up
      2
      ·
      edit-2
      3 months ago

      to be even more pedantic, if we follow the relevant official RFCs for http (formerly 2616, but now 7230-7235 which have relevant changes), a 403 can substitute for a 401, but a 401 has specific requirements:

      The server generating a 401 response MUST send a WWW-Authenticate header field (Section 4.1) containing at least one challenge applicable to the target resource.

      (the old 2616 said 403 must not respond with a request for authentication but the new versions don’t seem to mention that)

  • ShortFuse@lemmy.world
    link
    fedilink
    arrow-up
    14
    ·
    edit-2
    3 months ago

    Don’t use JSON for the response unless you include the response header to specify it’s application/json. You’re better off with regular plaintext unless the request header Accept asked for JSON and you respond with the right header.

    That also means you can send a response based on what the request asked for.

    403 Forbidden (not Unauthorized) is usually enough most of the time. Most of those errors are not meant for consumption by an application because it’s rare for 4xx codes to have a contract. They tend to go to a log and output for human readers later, so I’d lean on text as default.

    • BrianTheeBiscuiteer@lemmy.world
      link
      fedilink
      arrow-up
      2
      ·
      3 months ago

      I would actually encourage error responses be in JSON if your 200 responses are JSON. Some clients are apt to always convert the body to JSON so it could avoid an exception on the client side not to throw a curveball.

      To your point it’s most important that the content and Content-Type header match.

      • lemmyvore@feddit.nl
        link
        fedilink
        English
        arrow-up
        4
        ·
        3 months ago

        If any client app is blindly converting body to JSON without checking (at the very least) content type and size, they deserve what they get.

        If you want to make it part of your API spec to always return JSON that’s one thing, but don’t do it to make up for poorly written clients. There’s no end of ways in which clients can fail. Sticking to a clear spec is the only way to preserve your sanity.

  • fart_pickle@lemmy.world
    link
    fedilink
    arrow-up
    13
    ·
    3 months 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…

    • bitfucker@programming.dev
      link
      fedilink
      arrow-up
      1
      ·
      3 months ago

      It usually goes down like this on some security heavy system: It does not know that a queue is missing. It does however know that it cannot access that queue. When an error is thrown on a secure system, usually the first thing to check is the privilege. If the queue does not exist, so does the privilege to access said queue hence the first error being thrown.

  • calcopiritus@lemmy.world
    link
    fedilink
    arrow-up
    13
    ·
    3 months ago

    My favourite is when every error is an HTTP Bad Request with no body. Absolutely wonderful to use those APIs

  • Dunstabzugshaubitze@feddit.org
    link
    fedilink
    arrow-up
    12
    ·
    3 months 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.

  • snowe@programming.devM
    link
    fedilink
    arrow-up
    12
    ·
    3 months ago

    Anything but the last one. Don’t duplicate the http code in the body, else you’re now maintaining something you don’t need to maintain.

    I’m not a fan of codes that repeat information in the body either, but I think if you had used a different example like “INVALID_BLAH” or something then the message covered what was invalid, then it would be fine. Like someone else said, the error data should be in an object as well, so that you don’t have to use polymorphism to figure out whether it’s an error or not. That also allows partially complete responses, e.g. data returns, along with an error.

  • lengau@midwest.social
    link
    fedilink
    arrow-up
    11
    ·
    3 months ago

    At a previous job we had an unholy combination of the last two:

    HTTP/1.1 200 POST /endpoint 
    {
      "data": null,
      "errors": ["403", "unauthorized"],
      "success": false
    }
    
      • lemmyvore@feddit.nl
        link
        fedilink
        English
        arrow-up
        1
        ·
        3 months ago

        It’s a perfectly fine way of doing things as long as it’s consistent and the spec is clear.

        HTTP is a transport layer. You don’t have to use its codes for your application layer. It’s often done that way but it’s not the only way.

        In the example above the transport layer is saying “OK I’ve delivered your output” which is technically correct. It’s not concerned with logical errors inside what it was transporting, just with the delivery itself.

  • Tellore@lemmy.world
    link
    fedilink
    English
    arrow-up
    11
    ·
    3 months 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.