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.