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.
just 403 and leave the body empty
Good enough in most cases. Too much info and it might as well give step by step instructions on how to hack you.
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
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.
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?
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-adf68e5cf1f8This one looks nice. Very detailed.
This is the right answer imo. While it might be an overkill for sth like 404s, it’s amazing for describing different bad requests.
GitHub has OpenAPI specification. Latest version is 3.1, I think.
Looks like they’re recommending object of error code (number) and message.
I really like the fifth one. So you might always get a surprise message in your response
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…
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.
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?
Giving back a 200 for an error always makes me bristle. Return correct codes people. “But the request to the web server was successful!”
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.
I use this big expensive simulator called Questa, and if there’s an error during the simulation it prints
Errors: 1, Warnings: 0and then exits withEXIT_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).
That’s when you use different exit codes. 1 for failure during simulation, 2 for simulation failed.
Shame they wouldn’t listen.
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.
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.
My favourite is when every error is an HTTP Bad Request with no body. Absolutely wonderful to use those APIs
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 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
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.
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.
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.
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.
This guy backends ☝️
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 likeError 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 .-.
