Wow, the example in the article is an
extremely verbose error message! But still, detailed and helpful error messages really do make the developer's life easier.
When building API end points, I take a different approach by including both messages and message codes, as well as a general "result" code (to make it easy to determine if it's a basic success/error result (also including the right HTTP code)).
An example that I'm working on right at the moment:
{
"result": {
"code": "error",
"message_code": "too_many_user_agents",
"message": "You have sent %s user agents; this is more than the maximum allowed per batch (%s user agents). Please send fewer in each batch."
}
}
The message describes the problem; what they did wrong, what the limit is and how they can fix it so it doesn't happen again.
As well as this, the developer can easily check that the response code was an error, and there's the message_code - this will NEVER EVER change for this problem, so a developer could write code to specifically deal with that scenario.
However there's also a human readable message, which may potentially change (perhaps a grammar or punctuation fix, or if it included a URL it might change one day...)
I've found this approach is the best sort of middle ground.