5 ms·

Nit: Really verbose error messages like the last example are at risk of being brittle. If the API changes, there may be a failure to update the error message. T

Nit: Really verbose error messages like the last example are at risk of being brittle. If the API changes, there may be a failure to update the error message. This is because the messages may concern things at a distance, and may have arbitrary prose that no longer makes sense. For example, imagine if all your error messages were basically documentation style prose. That would be a nightmare, and would set you up to a lot of error message refactoring. A better strategy is somewhere in the middle.

afarrell 9y ago
Links to broader descriptions in your docs are one useful tool here. As is having a hook in github which notices that a PR updates your API schema and adds a comment with a checklist of things to be sure you've considered.
greggman 9y ago
I thought it was a good idea when an error message says bad request type, see http://company.com/API/ce32h except that it always seems the company forgets and removes the page. maybe that could be fixed to some degree in a build step
whatismybrowser 9y ago
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.

afarrell 9y ago

Links to broader descriptions in your docs are one useful tool here. As is having a hook in github which notices that a PR updates your API schema and adds a comment with a checklist of things to be sure you've considered.

greggman 9y ago

I thought it was a good idea when an error message says bad request type, see http://company.com/API/ce32h except that it always seems the company forgets and removes the page. maybe that could be fixed to some degree in a build step

whatismybrowser 9y ago

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.