5 Most Common API Errors and How to Fix Them

As software got more complex, more and more software projects rely on API integrations to run. Some of the most common API use cases involve pulling in external data that’s crucial to the function of your application. This includes weather data, financial data, or even syncing with another service your customer wants to share data with.

However, the risk with API development lies in the interaction with code you didn’t write—and usually cannot see—that needs debugging. This makes error identification critical, so you don’t waste development time trying to fix the wrong problems.

Luckily, some errors are more common than others, and these are the best place to start looking when your API calls aren’t working as expected.

In this article, we’ll explain how you can spot these errors in your own code, fix them, and get back on track.

Using HTTP Instead of HTTPS

Security on the web is crucial. And as more and more websites adopt HTTPS over HTTP, API endpoints should do the same. If the API is developed with this potential error in mind, you should get an informative error. Informative errors tell you to access the endpoint via HTTPS rather than HTTP.

For example, a response might look like this:

This is a best-case scenario, because this error message tells you how to fix the problem: by making an HTTPS call, instead of HTTP.

However, when an API is built without this potential error case in mind, it can masquerade as other errors we’ll discuss later. With a very similar case, a less resilient API might produce the following:

• 500 Internal Server Error: One of the least helpful errors, 500 Internal Server Errors mean the server can’t handle the request. However, this can also happen when you pass incorrect or incomplete information to the API (or when it’s simply broken).
• 403 Forbidden: Depending on how the API infrastructure is set up, you might get a 403 Forbidden error. While you may have incorrect credentials, this could be the result of an undetected HTTP vs. HTTPS error as we discussed earlier.
• 404 Not Found: Some servers don’t have HTTP endpoints, so they return 404 errors. leading you to believe you’ve mistyped the endpoint URL or something similar.

Nowadays, most API endpoints use HTTPS, so it’s usually safe to assume you should be calling the HTTPS endpoint. If you’re not, and you get one of the errors listed above, this should definitely be one of the first things you check.

Using the Wrong HTTP Method

Even if you’ve never accessed an API method before, you use the GET method every time you access a website in your browser. But when it comes to APIs, different endpoints require a different HTTP method (GET, POST, PUT, PATCH, or DELETE) depending on what action you’re trying to complete. For example, if you’re trying to access the Twitter API to get a list of a user’s tweets, you’d likely be calling a GET endpoint. If you’re trying to tweet as that user through the API, you’d likely use a POST method.

Those are by far the most common methods, although PUT and PATCH are sometimes used to update existing records in a database that’s behind an API, for example.

As with the previous example, this can be a straightforward error to detect. If the API recognizes the route but can tell you’re using the wrong method, sometimes it will just tell you:

However, in some cases, this error can present as one we’ve already discussed:

• 500 Internal Server Error: If the server doesn’t know how to handle receiving the incorrect method gracefully, it may just fail completely and give you a 500 Internal Server Error. In this case you may have to look deeper into the error logs to debug.
• 403 Forbidden: Depending on how the server is configured, it may not allow you to access any of the endpoints with the incorrect method and will return a 403 error. You may be tempted to check whether your authentication is working correctly, when the problem may really be an incorrect method being called on the endpoint.
• 404 Not Found: Some API frameworks simply return a 404 error when the incorrect HTTP method is used because your request doesn’t match a known route.

When your API call returns an error, you should double check the documentation to make sure you’re using the correct HTTP method. You should do this even when the error you’re seeing is not the 405 error that explicitly indicates you’re using the wrong method.

Using Invalid Authorization

APIs beyond the most basic usually require some sort of authorization. Sometimes that’s an API key, a username and password, an OAuth token, a JSON Web Token, or a custom authentication method.

What’s important is that this authorization is provided with each and every API request. This ensures that the API knows the requester has adequate permissions for the operation being requested. When these credentials are incomplete or incorrectly formatted, the API in question can produce a variety of errors. Typically this will be the 403 Forbidden error, which tells the user they’re not allowed to access that particular resource.

In that case you should check your credentials, as well as the API documentation, to make sure they’re formatted correctly. For example, some APIs require a username and password separated by a : character, some require credentials to be base64 encoded, and some have different requirements entirely.

It’s important to make sure you’re following the parameters laid out in the documentation so that your credentials are accepted.

Caching Errors

Especially in cases where APIs are heavily used, results may be cached to improve performance for everyone who has API access. This is usually very beneficial, as it provides everyone with the ability to get data when they need it. However, there are two potential cases where this approach is problematic.

In the first case, the information from the API may be cached and outdated as a result. In this case, discuss with your team whether this caching time can be reduced—without affecting API performance.

The second—and more difficult case to debug—is when an error state is cached. This can lead to an API returning an error, even if it’s actually been resolved. To fix this, check with your API provider to see if there is a testing environment that doesn’t utilize caching.

Alternatively, double check your API call on a different machine or with a different set of credentials. You can also check your API documentation to see if there’s some cache invalidation method available. In some cases, the API cache can be invalidated manually, but this shouldn’t be done regularly as it removes the benefits of caching in the first place.

If you’re encountering an error we’ve discussed above yet believe you’ve fixed all the possible root causes, see whether the response is cached on either the API side or in your API client.

Invalid Fields

If you’re passing data to an API instead of just receiving it, it’s important to provide all the data the API expects, and (in most cases) ignore data it doesn’t support. Always read through the endpoint documentation for any API endpoint you’re trying to access, and make sure you’re passing the correct data. If you aren’t doing this, you’ll hopefully get a specific error message telling you about missing or extraneous data.

It’s also possible the API will return a 500 Internal Server Error if it cannot handle an unexpected response properly. If you encounter this error and have already run through the debugging steps for each of the previous errors, double check your data to make sure it matches the specification indicated in the API documentation.

Wrapping Up

Working with APIs can be intimidating for many because of having to interact with code they don’t directly control. This often means a developer’s more traditional debugging methods are not possible. However, with experience you’ll start to know what to look for when you encounter various API errors, allowing you to fix them faster. With these errors resolved, you’ll be powering your application with APIs and external data, and improving user experience as a result.