How to Debug Common API Errors

Introduction

Every software developer that works with APIs has to debug APIs at some point. In an ideal world, API always returns either with a 200 OK status with the correct data, or in case of a failure, it returns the exact status code and error message that allows us to easily understand what went wrong. API users can make requests with typos or mistakes that APIs do not know how to handle.
Let us discuss how to debug common API errors that might occur while working with APIs.

Status Codes

When working with APIs, every HTTP request that is sent to the server will respond with an HTTP status code. Following are the five different categories for HTTP status codes:

• 1xx – Informational
• 2xx – Success
• 3xx – Redirection
• 4xx – Client Error
• 5xx – Server Error

The 4xx Client error and 5xx Server error codes are the more common API errors that can usually be solved by the API user itself.

General Tips

Following are some of the certain tips that we can apply to any API debugging attempt:

1. Use an API Testing Tool: Use API testing tools such as Postman, Runscope, cURL, HTTPie that allow us to make, edit, replay, and inspect API calls. These tools are free or have some trial period and can save a lot of time. Another advantage of using a tool is that it can help us isolate an issue due to a bad API call, or something in our app environment like a configuration issue, firewall, etc. that prevents the API request from returning a 200 status code.
2. Read the Docs: Please read the API documentation carefully. Reading the docs can be the difference between being stuck with an issue for an hour, or making a successful API call and moving on to your next task.
   Well-written API documentation includes how to authenticate, how to get an access token, what methods and endpoints are supported, and what errors we might come across, and how to handle them.
3. Be Careful with Copy + Paste: Be careful while copying and pasting code from API documentation or Stack Overflow answers. Given examples can be outdated or use an old version of API that is not supported anymore. Also, sometimes Copy + pasting code change the meaning of certain characters that might completely change how API calls work.
   Now, let us learn about some specific status codes.

400 Bad Request

A 400 status code means that the server could not process an API request due to invalid syntax. A few possibilities why this might happen are:

• A mistake while building out the request manually, such as mistyping the API endpoint, a header name or value, or a query parameter. This can also be caused if the request is missing a required query parameter, or the query parameter value is invalid or missing.
• A malformed JSON body, for example, missing a set of double-quotes, or a comma. Always prefer using JSON lint to make an API request with a JSON body.
• The request is missing authentication information, or the Authorization header provided could not be validated

The main advice when debugging a 400 Bad Request error is to review every piece of text. Make sure there are no typos in the endpoint, headers (name and values), and body.

401 Unauthorized

The 401 Unauthorized status code is returned when the API request is missing authentication credentials or the credentials provided are invalid.
APIs can be unstable especially while creating and formatting the Authorization header. For example, OAuth 2 tokens need to be prepended with “Bearer” for them to work:
Authorization: Bearer your_api_token

And when using HTTP Basic authentication, pay close attention to the syntax of the header value. The form is as follows:
Authorization: Basic base64_encode(username:password)

And there are some cases when we have only a username or a password, make sure to include the colon (“:”) before encoding. Otherwise, the authentication will fail.

403 Forbidden

The 403 Forbidden status code looks similar to the 401 code, but they should not be confused with each other. The 403 status code means that the server does recognize the authorization credentials and accepts is as valid but the authenticated user cannot access the resource for that endpoint.
For example, the user might be trying to access account-level information that is only permitted by the account administrator, and the credentials being passed on the API request are for a regular user account.
Another reason is that the user did not request an API access token with the correct permissions.
To fix the API call for these two situations, make sure that the credentials used have the access level required by the endpoint, or that the access token has the correct permissions.

404 Not Found

404 Not Found status code can usually mean a few different things:

• The endpoint does not exist
• The endpoint exists, but the resource cannot be found
• The endpoint exists and the resource can be found, but the user does not have the required permissions to access it, and so the server returns a 404 status code

For the first two cases, double-check that the endpoint really does exist in the documentation, or that there are no misspellings or typos.
For the third case, make sure that the authorization credentials being used actually have access to that endpoint.

429 Too Many Requests

The 429 Too Many Requests is one of the longer ones and self-explanatory.
There is some form of rate-limiting for public and 3rd-party APIs to limit how many requests the user can make over a period of time. This serves to protect the API provider from having a user making too many API calls, which can take up too many resources and cause API slowdowns or even crashes for users.
Following are several things that we can try to fix:

• A Retry-After header might be included, indicating the date or time in seconds when the user can retry the request
• Check the API documentation for the specifics of their rate-limiting. Upgrade their accounts, or reach out to the API support team to increase the rate limits.

5xx Error Codes

5xx status codes mean that the error is on the server side, not on the user side. Some of the more common status codes you might encounter are:

• 500 Internal Server Error
• 502 Bad Gateway
• 503 Service Unavailable
• 504 Gateway Timeout

So the general advice is to:

• Try again later. The server might be under too much load at the moment
• Check the API status page for more information if there is maintenance going on or the API is down

If you have skills in PHP programming and you want to enhance your career in this field, a PHP certification from StudySection can help you reach your desired goals. Both beginner level and expert level PHP Certification Exams are offered by StudySection along with other programming certification exams.