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.
You must log in or register to comment.
Anything except the 2nd to last one, which is, unfortunately, mandated by my employer’s internal code style guidelines. 🫠
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…
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.
Ugh, poor error reporting is such a frustrating time sink.
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.
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 interpretationAs json usually but if you’re all using protobuf, go off King.
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
I’ve never heard of using protobuf in an HTTP API… But, I guess that should be fine.
The thing is, it does exists a way to convert grpc protobuf to json one
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
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…
“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
so the creator of gif himself was deliberately transgressive?
You missed the point:
The original creator of a thing does not control the current usage.
It’s analogous.
I don’t get why the RFC show an example returning 403 with body “You do not have enough credit.” although there is a dedicated status code " 402 Payment Required". Isn’t more correct to use 402 in this situation?
This is the right answer imo. While it might be an overkill for sth like 404s, it’s amazing for describing different bad requests.
This one looks nice. Very detailed.
Don’t know what are the changes since 7807 (which this one obsoletes) but this article helped me quickly understand the first one, hopefully it’s still somewhat relevant.
https://lakitna.medium.com/understanding-problem-json-adf68e5cf1f8
I like using Problem detials
It’s fully supported by the .net server pretty much out the box and just seems nice to stick to a standard where possible.
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?
It’s 401 unauthorized or 403 forbidden, not 403 unauthorized
You’re right, I was just giving an example though.
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)
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.
I’ve mistyped, I meant message in JSON body :)
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.
HTTP/1.1 403 UNAUTHORIZED { "error": { "status": "UNAUTHORIZED", "message": "Unauthorized access", }, }I would separate the status from the HTTP status.
- The HTTP status is great for reasonable default behaviours from clients.
- 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.
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.
I really like the fifth one. So you might always get a surprise message in your response
My favourite is when every error is an HTTP Bad Request with no body. Absolutely wonderful to use those APIs
1 or 3; maybe 4.
With several assumptions made, ultimately, they’re asking for json, and we should still return json, but what that looks like is up to you. It should be static enough that the person on the other end can write:
If json.grtnode(error) == "unauthorized access" Do stuffIfnyour going to be changing the text with some regularity to contain relevant information for the error (eg, an item ID, that is now invalid), then consider a code/text and additional fields.
The clown, but flipped with a
successfield. If it is true then command succeeded, if it false something was wrong and there should be anerrorfield 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.
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
What I meant was that if you are returning 404 for example when a user doesn’t exist. You can’t tell if the user doesn’t exist or someone changed the API to remove the endpoint.
But forcing HTTP codes without a moment to think it through seems to be the new fad.
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.
