API error handling: definition, example, best practices

API integrations can fail for a number of reasons.

Maybe you didn’t add the endpoint’s URL correctly; or you used an invalid or expired token; or you sent data in a format the API doesn’t support. 

Whatever the cause, your team needs to be able to diagnose the issue swiftly, identify the appropriate steps to remediate the issue on time, and execute those steps quickly and successfully.

In short, you need to build robust error handling processes across your API integrations. 

We’ll help you build these processes by breaking down an example and by highlighting several best practices worth implementing. But to get us started, let’s align on the definition of API error handling.

What is API error handling?

It’s the process of identifying and responding to a specific error from an API response with the goal of resolving the issue as quickly as possible. 

API responses typically provide specific error codes and messages (e.g. “404 Not Found”), which can help your team diagnose the issue. Your team is, however, on the hook for pinpointing the solution and implementing it.

Related: What is an API response code? Here's what you need to know

API error handling example

To help clarify our definition, let’s break down a specific example: Say you make a GET request to an API endpoint to retrieve details on a specific employee in an HRIS solution. However, the employee doesn’t exist in the HRIS solution—leading you to receive a “Not Found” error message. 

The log from this request is added to your monitoring tool. The tool then parses the log, extracts key information (e.g. the error code), and—if configured—alerts the relevant stakeholders of the error. From there, your developers can review the request to make sure it was formatted properly, analyze the error in conjunction with others to determine if it’s part of a trend, and more.

API error handling best practices

Here are just a few ways to implement error handling effectively.

Configure your monitoring system to accommodate payload details

API responses often include details that extend beyond the status code and error message. For example, there can be a longer message that describes the error; a timestamp that shows when the error occurred; a suggestion for addressing the error; and even a link to documentation that can help your engineers troubleshoot it.

You should configure your monitoring system so that it can capture this additional information whenever it’s available. And while it’s not always helpful, it can potentially help your engineers understand integration errors more easily, which better positions them to troubleshoot and resolve issues faster.

Related: API logging tips

Use exponential backoffs for server-side issues

In many cases, the error is on the API provider’s end. When it is, you’ll receive a 5xx error that can specify why, exactly, the server-side error occurred.

Whenever you find yourself in this situation, you can use exponential backoffs—which allow you to retry a specific API call at increasing intervals when they lead to failed requests. This gives the server time to recover, minimizes your number of failed requests, and likely saves you money, as you don’t have to make as many API calls.

Note: You should also use exponential backoffs when you receive a 429 error; this type of error indicates that you’ve sent too many requests in a certain period of time and may be violating the API provider’s rate limiting policy.

Integrate your monitoring system with Slack and/or your email service provider

Your engineers may not see issues crop up in your monitoring tool quickly, leading the issues to persist. Moreover, there can be so many logs to sift through that your engineers may have a hard time finding the issues that they’re equipped to solve.

To address both of these issues, you can integrate your monitoring system with your business communications platform (e.g. Slack) and/or email service provider. You can then build an automation where once a log with a certain status code comes in, a notification goes out automatically to the appropriate individual or team through Slack or email.

Document each error handling process

As the engineers who manage your integrations leave, you don’t want them to take their knowledge of your error handling workflows with them. This can leave your remaining engineers poorly-positioned to manage issues when they crop up, leading the issues to go unresolved for a longer duration.

In addition, as new engineers join your team, the process of introducing them to your error handling workflows can be time-intensive for your longer-tenured engineers.

You can tackle both of these issues by tasking your engineers with documenting each error handling process. The documentation can cover specific status codes in more depth, offer concrete steps for investigating and tackling each type of error, provide previous examples, and more.

Related: API polling best practices

Review each error handling process frequently

Your API error handling processes may not work as well as expected. Moreover, they may break or become less effective for a variety of reasons over time (e.g. the 3rd-party APIs you've built to change or undergo version updates that lead them to use new error codes or different error response formats).

To help your team spot any error handling workflows that don't perform up to par, you can review each error handling process' performance with the relevant stakeholders consistently, such as every month.

Manage any API errors with ease through Merge

Merge, which is a single API that lets you add hundreds of integrations to your product, can automatically detect issues and provide steps for remediating them. Your customer-facing team can then pass along these steps to the affected client quickly, enabling the client to resolve the issue with little delay. 

In addition, Merge offers fully-searchable logs to help you find and diagnose 5xx issues. And we provide integration maintenance—through our partner engineering team—to solve for countless edge cases across your integrations.

You can learn more about Merge’s integration management features, maintenance support, and  Unified API by scheduling a demo with one of our integration experts.

API error handling FAQ

In case you have more questions on API error handling, we’ve addressed a few more below:

What are some popular REST API error codes?

The error codes are bucketed into 5 categories: 1xx, 2xx, 3xx, 4xx, and 5xx. Each category has a high level meaning, while the error code within a category lets you determine what, exactly, happened.

Here are some common error codes per category:

• 1xx (informational; server lets the client know that the request is still processing): 100 Continue, 101 Switching Protocols, and 103 Early Hints

• 2xx (Success; the client’s request was successfully received and processed): 200 OK, 201 Created, and 204 No Content

• 3xx (Redirection; the request was received, but in order to process it successfully, the client needs to take additional actions): 301 Moved Permanently, 307 Temporary Redirect, 300 Multiple Choices

• 4xx (Client Errors; the client’s request was flawed in some way): 404 Not Found, 401 Unauthorized, 403 Forbidden

• 5xx (Server Errors; the server experienced an unexpected issue that prevented it from processing the request successfully): 500 Internal Server Error, 502 Bad Gateway, and 503 Service Unavailable

How should you test your API error handling processes?

You should write tests that cover every potential issue. That way, you can evaluate each process and confirm that it works as expected. If, however, you have limited resources and can only test for a certain length of time, it’s worth prioritizing common HTTP status code errors, like 404 Not Found, 401 Unauthorized, and 503 Service Unavailable.

In addition, you should use an automated API testing tool, like Postman or SoapUI, to save your engineers’ time and perform more tests quickly.

What is an API error handling strategy?

It’s the set of steps an organization takes to monitor and address response errors. This involves deciding on the employees who need to participate and how they’re involved. And it includes alignment on the tools that are used and the capacity in which they’re leveraged.