Navigating the API Error landmines
By: Chethan Babu
Tags: Api Design, Api Implementation, Error Handling, API, Api Development

Errors in API Design

All APIs are truly successful in an enterprise only when you design them to handle errors reliably and gracefully. Most APIs are built only for the success scenarios or handle the error scenarios so haphazardly that they give an impression of landmines which can go off at any time and the team would have to scramble to support when it all goes wrong. Why is it so hard to implement a successful and reliable error strategy in an organization? Is there a simple way to get started?

Table of Contents

API Error handling fundamentals

Before we get started with enterprise error handling process, let’s get some fundamentals out of the way — so that we are on the same page.

API vs Enterprise API

In any integration scenario, interaction between an API consumer and API provider happens one on one.

But, in an enterprise an API does not stand alone. There will be more than one API in an enterprise—and they come in different sizes, functionality and trust levels. So, while designing and implementing APIs, we should always think Enterprise API instead of a single API — so that all APIs in the organization will look and behave in the same reliable fashion.

Enterprise API is the progenitor of all APIs within an enterprise. It stands to reason that API error handling also should stem from the Enterprise API!

In this article, wherever API is mentioned, it indicates Enterprise API unless otherwise specifically mentioned

API error handling considerations

Whenever we talk about error handling in general, we immediately get the answer of two types of errors:

Technical errors — like Network being down, database not available, etc

Business errors — like Validation error from the business applications, authorization issues, etc

But when we look at API error handling, we should also have the following actors as additional considerations:

API Consumer — Many of the consumers will assume that APIs abstract the implementation logic, so most errors need to be abstracted from the consumer (unless there is a specific need to not abstract….). For example if the error is due to system XYZ connectivity issue, you will probably not want to tell the consumer that XYZ failed — rather only say that there has been a connectivity issue.

Support Team — Although the support team is not the primary caller of the API, they need to provide run time support to each of the APIs when things go wrong. For example, if an API fails due to connectivity issue, support team needs to understand that the issue is with system XYZ and not ABC. Even though error response didn’t contain these messages, they would need access to further information to help sort out the issue.

Last but not least, we need to understand the type of API we are building — especially from the point of view of who is responsible for errors in the API:

API Consumer responsible API— APIs in which API consumers are expected to handle most of the errors (by retry or handle issues). For example, you are using a customer creation or query API and it fails, the responsibility is on the consumer to try again and handle the errors (invalid post codes, wrong data types, network errors, etc). The API owner can take a look and fix the issue, but the responsibility to handle most of the errors falls under the scope of the API consumer

API Publisher responsible API — APIs in which API publisher takes ownership of the errors. For example, payment APIs which should take the ownership of all errors once triggered and API consumer is not expected to handle the errors (for example — no retry)

Now that we know the considerations we should have in mind to design an Enterprise API Error strategy, how do we go about designing and implementing such a system properly?