Getting Started with SP-API Error Handling 🎬🛠️

[mafge]

Handling errors is an integral and sometimes painful task when integrating with an API, especially when it is a complex and extensive one like Selling Partner API from Amazon. In this Hot Topic, we will have a look at the brand new Solution Provider Portal and how it can help with error handling, continuing with common errors that you might experience when working with SP-API and finally learning about important terminology, tools and strategies for error handling. This includes practical tips and tricks that can be applied right away to your applications without the need to reinvent the wheel.

This is part 2 of the SP-API Integration Best Practices series. In part 1, we focused on reducing SP-API call volume.

Authored by: Marc Gerzimbke (@mafge), Solutions Architect, Selling Partner Developer Services

Solution Provider Portal: Kick start your error handling efforts 🏃‍➡️

Solution Provider Portal is a great place to start our endeavor to improve error handling. Besides all the other great functionality it offers, there is one feature that is really helpful: API Usage Dashboard. This dashboard contains all important data points that are necessary to understand how your application is performing:

• API usage summary: Gives information about the number of apps registered in this account, overall call volume as well as current overall error rate.
• Breakdown on application level: Below the summary, there is a breakdown for each individual application. It contains all API section and operations per section this application is using, including important information like call volume and number of returned HTTP status codes.

API Usage Dashboard: API usage summary on the top, followed by a list of all registered applications for this account

API Usage Dashboard: Individual breakdown of important information (per API and operation) for specific application

Note

The data in the dashboard is refreshed daily, you can filter by application and time range (last 7 days to last 90 days).

In the next section, you will learn more about the meaning behind the different HTTP status codes you see in the dashboard and how they help you to derive insights into what errors are happening in your application.

Common HTTP status codes 🚥

The HTTP status code you see in the Solution Provider Portal can be grouped into three different categories:

HTTP Status Code	Examples	Category	Details
2xx	200 OK, 204 No Content	Successful responses	The request was successfully received, understood and processed.
4xx	400 Bad Request, 404 Not Found	Client error responses	The request was invalid and couldn’t be processed - this is the category of errors that needs special attention.
5xx	500 Internal Server Error	Server error responses	The server failed to fulfill your valid request.

Let’s have a closer look at common 4xx errors, that occur when working with SP-API:

HTTP Status Code	Details
400 Bad Request	The server has not processed your request because it doesn’t comply to the API specification (e.g. required parts of the request are missing).
403 Forbidden	The server has not processed your request because you aren’t authenticated and/or authorized to call this operation (e.g. missing/outdated access token).
404 Not Found	The server has not processed your request because the requested resource does not exist (yet).
429 Too Many Requests	The server has not processed your request because you sent too many requests in a given amount of time.

Knowing the meaning behind these status code gives you a hint on what could go wrong in your application and help to isolate the area in your code that causes these issues.

Tip

Use the data from the API Usage Dashboard to identify API sections and individual operations, that have a high number of 4xx responses compared to others. Our recommendation is to pick the top three operations with the highest call volume and error rate and focus on these ones first. The insights you are gaining when investigating and implementing measures to prevent these errors can then be usually applied to the less critical ones as well without too much overhead.

Leveraging automation 🤖

Important

The approach we took so far helps to gain valuable insights into your application, but it has some drawbacks:

• The data provided in the dashboard is not comprehensive enough to easily debug errors
• The dashboard needs to be checked manually on a regular basis

There is so much more we can do here to enable the systematic detection of errors in real time, the collection of valuable data that helps to debug errors and the automatic notification of stakeholders that are required to resolve the issue in a timely manner.

Before we can do that, we need to build a common understanding on some of the mechanisms that are available for error handling, namely logging, monitoring and alerting (in the context of software applications):

• Logging: Describes the process of recording and storing of important events that occur when running applications. These logs can be used afterwards to get an understanding on what happened before/during/after an error happened in the application. Finding the right balance between too much and too little logs is a crucial process that often requires time, learning and fine tuning to get it right. Examples for commonly used tools are: ELK (Elasticsearch, Kibana and Logstash), Grafana Loki, Graylog, SigNoz.
• Monitoring: Describes the process of observing, measuring, analyzing and typically also visualizing critical aspects of applications in real time. Monitoring allows the detection of system anomalies, critical data trends over time and is an important tool for decision making. Examples for commonly used tools are: Prometheus, Datadog, Dynatrace, New Relic.
• Alerting: Describes the process of notifying human and non-human resources in case of a danger, threat or a problem. Alerting usually works based on predefined rules, that are automatically triggered when a certain threshold has been reached. Examples for commonly used tools are: Splunk, Grafana, Datadog, New Relic.

Important

These three mechanisms serve a distinct purpose and should be used in conjunction.

Example 🏋️

Let’s quickly run through a fictional (yet realistic) scenario to showcase how each of the mechanism plays an important role in API error handling. A solution provider has deployed a new feature to its application. After a couple of hours, the alerting system sends a notification to the operations team because the error rate for one operation has reached a critical threshold. The operations team uses the monitoring tool to verify that the alert is actually valid and open a ticket with the development team adding all data and information they have from alerting and monitoring. A developer picks up the ticket and starts the investigation. By using the data from alerting and monitoring as well as logs he is able to understand the error - in some cases a required parameter is not set in the request which results in a HTTP status code 400 when calling the operation. Having all necessary data and tooling in place, said solution provider is able to implement a fix in a timely manner.

Note

Using logging, monitoring and alerting allows us to automate most of the critical work we did manually before. There is a wide variety of paid and non-paid tools for each of them (or combining all of them) available.

Final thoughts 🤔

Preventing errors and defensive programming are important parts of modern software development. Given the complexity and often distributed nature of modern software systems, it is also important to recognize that it is almost impossible to consider all possible errors beforehand. Therefore, it is equally important to establish capabilities to automatically detect errors and reduce the time to fix any error from first occurrence to the deployment of a issue resolution as much as possible. Using API usage dashboard from Amazon Solution Provider Portal is a great first step to start and fortunately, there is a plethora of different tools out there that can be used in order to automate logging, monitoring and alerting with minimal time and effort spent.

Make sure to check out part 3 of this series for a deep dive on common errors and how to fix them.

Additional resources 📚

• 📹 Video: Error Handling Best Practices for Selling Partner API
• 📖 Documentation: Optimize Rate Limits for Application Workloads

Let us know what do you think! 👇 React or reply down below to share your feedback. Happy error handling!

• ❤️ Like what you see?

• 👍 Excited to try it out?

• 🎉 Want to see more of this?

Keywords: #amazon-sp-api #error-handling #exception-handling #logging #monitoring #alerting #automation

Please note the publication date above. While we strive to keep our content current, the rapid evolution of this topic means some details may have changed since publication. For the most up-to-date information, we encourage readers to follow the announcements in SP-API developer documentation.