What makes a good error message (or API return code) ?

Yet another example just now of what must rank as a textbook example of the worst kind of error message - "Invalid Parameter":

https://devzone.nordicsemi.com/f/nordic-q-a/52898/error-0x000000007-invalid-parameter-in-advertising_init/213360#213360

The message is unhelpful in that it neither tells you which parameter was invalid, nor how it was invalid.

It is even worse in this particular case, because it can also happen when the parameters are each individually valid, but the particular combination is not allowed. 

So fixing the problem becomes a game of trial-and-error.

So what makes for a good error message?

(and in that, I'm including API return codes)

The key thing is that it must not just tell that something is wrong - it must give you sufficient information to know what was wrong, why it was wrong and, thus,  how to fix it!

In the case of the API return codes here, that probably means that one single code is not enough - there will need to be a number of codes, each describing a specific error.

Parents
No Data
Reply Children