Because of my current job, I’ve had to work a lot with how best to handle errors. For some errors, the root cause can be attributed to the user i.e. (1) the user needs to provide a specific (and correctly formatted) piece of data for the flow to proceed or (2) the user did something “wrong” (I use the word in quotes because the customer is always right, and we need to be careful when labeling their actions as wrong). For other errors, the root cause can be attributed to the software itself i.e. something went terribly wrong in the code and the user cannot proceed in the typical manner the user is used to (aka fatal errors).

My philosophy on errors:

Give the user three important pieces of information (if you can):
1. What happened? Explain, as concisely as possible, what went wrong.
2. Why it happened? Explain, (again) as concisely as possible, the root cause of the problem – in language the user understands (don’t tell the user that there was a Null Pointer Exception!!).
3. What next? This is the most important step. Explain to the user what they need to do in order to resolve the issue.

For fun, here is an example of a fatal error (from Facebook):