Common API Errors

Building an API can be easy, with certain tools and frameworks allowing developers to develop and implement one in a very short time. But building a secure, sturdy, and reliable API requires more time and effort. The API development process involves interacting with code that a developer did not write and cannot see. And since developers are human, it is common for errors to occur, and it is critical to identify and resolve them.

An API error can lead to an API outage, affecting several stakeholders. It can negatively affect a business’ reputation and lead to revenue loss if customers can’t access service. For instance, an API outage cost Facebook about 100 million US dollars in revenue in 2012.

Let’s understand what API errors are and discuss some of the most common API errors.

What are API errors?

An API error is a type of error that occurs when an application programming interface (API) fails to function.  It can occur when there is a problem with the way the API is configured or when there is an issue with the code that is using the API. In some cases, an API error can also be caused by a problem with the server that the API is hosted on. Other times, there may be an issue with the way that the API is being called. For example, if the wrong parameters are being used, this can cause an error.

Whatever the cause, an API error can result in unintended consequences for the systems that are using the API. For example, if an online shopping website encounters an API error, it could prevent customers from being able to add items to their shopping carts. An API error can have a significant impact on the usability of software, so it is important for developers to be aware of how to troubleshoot and fix these errors.

Categories of API errors

Though there are many scenarios for API errors, they are generally categorized into temporary and permanent.

• Temporary API errors occur when a request that was executing properly fails suddenly and returns an error message. A temporary issue with a server causes these errors, which are resolved promptly.
• Permanent API errors are caused by actions not allowed by an API and thus fail to execute. The API server will respond with a specific error message with the exact reason, such as a lack of security permission to access a particular feature. Sometimes, the server might send a generic error message without the precise reason.

Error codes are the most helpful diagnostic tools for identifying API errors. Error codes are generated in the response stage, which comes immediately after the request phase. It is the direct communication between the API and client and serves as an essential step in notifying the user about an API error and initiating the resolution process.

The most common API errors

Here are the most common API errors that developers need to be aware of:

1. Wrong HTTP

This is an easy but common API error that is caused by poor understanding of the documentation. The endpoints may fail to state the supported methods or contain the wrong verbs. When using APIs, endpoints need different HTTP methods depending on the action a user is trying to complete.

For instance, if a user tries to get a list of tweets, they will use a “GET” endpoint. If they try to tweet using an API, they will use a “POST” endpoint. Always confirm from the documentation whether you’re using the right HTTP method when you receive an error message. Error 405 states explicitly that you’re using the wrong HTTP method.

2.  HTTP instead of HTTPS

APIs support HTTP and HTTPS, but leaving an “s” when it should be used may lead to an error. Some APIs support HTTPS only, while some support both HTTPS and HTTP for some endpoints. Furthermore, APIs may reroute HTTP requests to their HTTPS, but not all frameworks do this.

It is also vital to stay updated because some APIs can stop supporting HTTP. Some API providers notify customers about such changes through social media handles and emails before implementing them.

3.  Wrong authorization credentials

Some APIs, particularly those implementing OAuth 2, require “Authorization” headers for each request. Confusing “Authentication” and “Authorization” is a common mistake, so make sure you are using the right word.

Another common issue with an “Authorization” header is construction. You must combine OAuth 2 with “Bearer” for it to work. Ensure the header value syntax is correct when using HTTP basic authentication.

4. Content-type header issues

Content-type and accept headers determine the type of information sent and received between a server and client. Some APIs accept requests without these headers and default to common formats like XML and JSON. However, more strict APIs need these headers on requests and will return an error 403 message if you fail to include them. Accept and content-type headers allow the server to identify a client’s request and what format they expect in return.

5. Invalid content type

This API error occurs when the server doesn’t understand what response format the user needs. Some servers and frameworks return a 500 HTML error. If the API does not return HTML, please check the default error response. The load balancer or routing mesh may also cause this error. A request timeout or other error that prevents a request from reaching the API may also return an HTML error.

6. Caching issues

Heavily used APIs often cache results to improve performance for users with the API access. Caching is great but may also result in a few errors. For example, the cached information may be outdated, leading to errors.

Discuss with the IT team about reducing the caching time without compromising API performance. A more difficult error to resolve is a cached error state, which may cause the API to return the error even when it has been resolved.

7. Invalid fields

Providing all the information an API needs is essential, but you can ignore unsupported data. Reading the endpoint documentation ensures you’re providing the correct data. You will receive an error message about the irrelevant or missing data if you input invalid fields.

8. Unforeseen  error codes

Though API error messages help developers identify and fix errors, sometimes they lack adequate information, leaving the developers with the heavier task of finding it out by themselves. API developers can streamline the development process by leveraging tools that provide links to error messages, thus allowing developers to troubleshoot any error in a code.

9. Poor team communication

When development teams fail to communicate effectively, API errors can cascade out of control. For instance, if the development team fails to communicate any changes to the support team, the support team will provide users with the wrong information and negatively impact their experiences.

10. HTTP redirects

Failing to acknowledge the details and inconsistencies of different API tools can lead to errors, especially in HTTP redirects. Small details can trigger a redirect, which can be tricky. A redirect may not be what the user requested at all. This may vary depending on the API and tools implemented.

11. Invalid or missing parameters

This error occurs when one or more required parameters are missing from the request, or when the values of some parameters are invalid.

12.  Request throttling

This error occurs when the API server is receiving too many requests from a particular client, and is therefore rate-limiting that client.

Conclusion

API errors can be frustrating for developers. They’re terribly bad for user experience. Therefore, it is important that developers pay attention to these errors and be sure to resolve them promptly. An unresolved error can easily cascade and lead to major issues down the line.