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.
The last one is very convenient. As an API consumer you can get all the necessary info from the returned payload, and the 403 will trigger the error path.
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.
I’ve never heard of using protobuf in an HTTP API… But, I guess that should be fine.
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?
GitHub has OpenAPI specification. Latest version is 3.1, I think.
Looks like they’re recommending object of error code (number) and message.
This is the right answer imo. While it might be an overkill for sth like 404s, it’s amazing for describing different bad requests.
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 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
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.
Security through obscurity isn’t security.
The documented one. It is hell to work with APIs where only the happy path is documented.
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.
I was annoyed that the one time I wanted to use 418 as a filler Dotnets http library didn’t support returning it.
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
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.
Probably not great to return server stack traces. Otherwise, yeah
I really like the fifth one. So you might always get a surprise message in your response
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.
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.
The status code that gets returned should be the status code of the messenger and not the data. If you want to add a status code about the data, then please do.
If something can return null and empty and it’s valid, that is not a 404. That is a 200.
As far as a 403, the messenger is telling you that you shall not pass. There is no data. 403 is appropriate here. The return response can be anything since 403 is pretty self explanatory, but I would probably return json to be consistent. I would also use the field message. Something like the first one for this use case only.
In other cases where i do get data, I would use data, message, status (optional). But status in the json response would be status about the message.
A simple error code is sufficient in all of these cases. The error provided gives no additional information. There is no need for a body for these responses.
There may be a need for additional information, there just isn’t any in these responses. Using a basic JSON schema like the Problem Details RFC provides a standard way to add that information if necessary. Error codes are also often too general to have an application specific meaning. For example, is a “400 bad request” response caused by a malformed payload, a syntactically valid but semantically invalid payload, or what? Hence you put some data in the response body.
A plain 400 without explanation is definitely not great UX. But for something like 403, not specifying the error may be intentional for security reasons.
I know of some people that never use 403, but instead opt for 404 for security reasons. 403 implies that there is something they could have access to, but don’t.
I think in some situations that this can be valid, but it shouldn’t be a crux.
404 is definitely also used sometimes for hiding stuff that shouldn’t be seen, but 403 may still be appropriate for various stuff where there is nothing to hide. With 404 you probably also never want to give any explanation or error message.
Have a code, where you can really describe the error; try to use the correct HTTP status (your example doesn’t); don’t ever use status 200 for errors; and finally, have an “error” key set to something somewhere (I’d write the error code to it).
The message is optional.
So, the simplest version would be:
HTTP/1.1 401 POST /endpoint { "error": "UNAUTHORIZED" }Status 200 for errors is common for non-REST HTTP APIs. An application error isn’t an HTTP error, the request and response were both handled successfully.
