How to Improve API Errors With Defensive Design

API errors can occur on a regular basis. It happens. But the real issue arises when API providers don’t give errors the attention they deserve, causing issues for developers attempting to use the API. In this post on the Luno blog, Simon Tabor discusses defensive design for handling API errors.

It has been said many times before, but an API is only as good as its documentation. So, errors should be clearly documented and follow a consistent format, including an appropriate error code and descriptive message, as well as any additional information.

Many APIs return a numerical error code that identifies the nature of the error, but it can be difficult for developers to remember what each code means. If the error was caused by a 'missing_param', then issuing that as the error code will be far more useful than a numerical code. However, even this type of error code accompanied by a descriptive message is still not enough information to fix the issue.

The most useful responses also provide details of what parameter is missing and include any extra information that might help the developer resolve the issue without having to search the documentation. Tabor’s stance is, if it will help your users, include it in the response as there is no reason to try and keep your errors small.

This entire job is made far easier by having a configuration file that defines all potential errors and generates your error reference in the documentation. APIs that export their configuration and routes help to keep the documentation up-to-date. Ultimately, it comes down to keeping your users happy, which will keep them using your API.

Original Article

API Errors – The Good, the Bad and the Ugly

Martin W Brennan Martin W Brennan is a co-founder of ViewPop, the social network that puts the creation of 3D photos and videos in the hands of anyone with a smartphone. For his day job, Martin is a copywriting consultant at We Write Words, learning about the world as he writes about it.

Comments

Comments(1)

cesutherland

Nice post!  Human readable error descriptions are great, and a machine-readable code (eg. missing_param) helps with automatically handling those errors or searching documentation for solutions.

If you do have a catalog of documented errors, it's great to include a link right to an error's documentation along with the response!