TL;DR
Do not mask API errors in UI, period.
Disclaimer
This post is potentially biased and contain content that may be treated as “ranting”.
Some websites and UI love generic error messages
Often, in websites here and there, I observe submission errors with some very generic wording, “Something went wrong, please try again later”, or “Submission failed”. This kind of error is usually tied to some missing or mismatching parameters sent from the web form to a service API or backend, or due to some issues with user permission/access control.
If one pulls up the console log or network inspector, they would usually see the actual error that the service backend is complaining about (except for when there’s some 500 error on the server side). However, website maintainers (likely asked by some Product Managers, or shortened as “Product” 🙃) often go out of their way to hide these error messages, and prefer showing “Something went wrong, try again later”.
Points made by UI defenders
Typical arguments for masking the actual errors include:
- Hiding technical terms is less confusing for the user
- API errors are less polished and not well-defined for users to read
- “Our UI needs i18n (ai-eighteen-en), and these service side errors are not translated”
- There are security concerns that bad actors may leverage these errors to exploit our systems
Stop masking them, none of the rationale stand
Speaking from both a user’s perspective and a service maintainer’s perspective, I cannot empasize enough, hiding errors in UI is very annoying and does not help anyone, anywhere.
A typical debugging scenario from a user’s standpoint
Imagine that a website hits an error and shows “Something went wrong, please try again later” when what the user actually has to do is filling in an overlooked text input not highlighted in red or checking an agreement box:
- If the user is a technical person, they might luckily know to inspect the webpage, check console logs or network request history to try to figure things out;
- If ther user is not, then they are left helpless, until some engineer on the service side responds indirectly via some customer service representative asking for screnshots 5 business days later. Then, the user attaches a screenshot they saw that says “Something went wrong, please try again later”, leaving the engineer at the other end scratching their head trying to locate service logs without an identifiable string, or figure out a way to reproduce the error.
- Another possible outcome is that the potential user leaves the page, never coming back again.
Arguing against masking API errors
Admittedly, showing a nice little chunk of “Something went wrong, please try again later” makes the content layout controllable and does not pollute the UI with unexpected text. However, “nicer looking UI” does not outweigh the severe harm done by doing so.
Hiding technical terms is less confusing for the user
First of all, if a UI normally looks nice, but it malfunctions for some actions, and some useful but clumsy error pops up, it is much more likely for a user to unblock themselves by making calculated guesses and finish what they have been up to. This is way better than putting the user in misery when they cannot perform certain actions and do not have the slightest clue apart from keeping retrying with exactly the same information.
API errors are less polished and not well-defined for users to read
As website maintainers, while one can certainly work towards polishing responses from the backend, showing something less polished but meaningful to the user is still far far far better than showing some information with little to none value.
“Our UI needs i18n (ai-eighteen-en), and these service side errors are not translated”
It is already half past the second decade of the 21st century, and there are already exceedingly mature machine-based multi-language translation tools that nearly any user of the internet has access to and has used at lease at some point of their life. While having official local translations does sound fancy, it is still way better to show non-native content rather than hiding them.
There are security concerns that bad actors may leverage these errors to exploit our systems
Unless the subject is a platform-native app that has tailored and well-guarded logging mechanisms (btw, certificate pinning is a bad idea, as they expire, but that’s another discussion for another time), anyone can inspect network traffic by hitting F12 on the keyboard (or equivalent shortcut) or via another web debugging tool. This is especially true for bad actors, the exact group of people this argument tries to guard against the most. The better altenative to guarding against bad actors than hiding an error message in UI is to hide stacktraces (which should be the default option for the production mode of almost all service libraries).
The bottom line
As a bottom line, if the website owner is not a fan of showing lengthy error messages in their UI, at least
- include meaningful error codes (that correspond to a dictionary that is either public or an engineer sitting behind the server can refer to internally); and/or
- show request IDs in the catch-all UI error
These are very effective and easy-to-implement mechanisms that would drasitcally gain the good of both worlds.
Thanks for reading.