6 Frequently Occurring API Errors And How to Prevent Them From Happening

APIs are an increasingly important part of the 21st-century economy and our everyday lives. Huge companies like Stripe and Amazon were built on excellent developer platforms. Even “analog” tools like office phone systems are becoming exposed to APIs. Increasingly advanced VoIP products integrate phone systems for small businesses with software like Google Workspace. This opens up powerful new experiences for employees and customers alike. But APIs aren’t above errors. Whether you are a hobbyist project developer or a million-dollar SaaS-based product user, you will find that glitches are inevitable.

What is an API Error/Failure?

An API error occurs when a server fails to locate the requested resource from the API provider. In such instances, a numeric error message is returned to help identify the specific error. Common causes of API errors include issues in the endpoint, incorrect parameters, or problems with the API key during the request call. Resolving these errors is crucial for seamless communication between applications and ensuring successful data retrieval from the API provider.

6 Common API Errors

Some common API errors are:

• HTTP/HTTPS errors.
• Unhelpful API errors.
• Method mixups.
• Missing Content-Type/Accept headers.
• Authorization errors.
• Data formatting errors.

1. HTTP/HTTPS Errors

One of the most common API errors occur when there’s confusion between http:// and https:// protocols in URLs.

For developers, the trouble is that some APIs only support HTTP protocol while others are HTTPS-compatible. Some support different standards at different endpoints in the same customer-centric product.

This can get even more confusing when developers are stringing multiple APIs together. If they’re in-house developers building “DIY” solutions for asynchronous business communications with remote teams. Developers have to spend time locating the endpoint that’s causing the problem, then create a workaround to get the two rest APIs to talk to each other.

If you’re an API provider, you can prevent this error by having specific HTTPS strategies in place. For example, you could have your API automatically redirect HTTP requests to HTTPS requests as they come in.

2. Unhelpful API Error Messages

For your users, the quality of your error messages can be the difference between a brief hiccup and an hour spent tearing their hair out, which helps in reducing customer churn.

HTTP provides over 70 http status codes, but at minimum, you only need to implement the most common ones developers are used to working with. Examples of those include:

200 OK

All good! Just be careful to only provide this status code if everything actually is OK. Facebook’s Graph API has been known to provide a 200 code whenever it successfully returns some output, even if that output contains an error code.

400 Bad Request

This is almost always due to a typo in your user’s input. But that doesn’t mean you’re off the hook! Make sure your error message provides some specifics about the faulty input so the user can quickly fix it.

401 Unauthorized

This status means the input is fine but the users’ request is missing an authorization code. Not to be confused with…

403 Forbidden

This means the authorization code is recognized as valid but the user doesn’t have permission. For example, a user could be trying to access something only available to the admins, an increasing security concern with remote staff.

404 Not Found

The user’s request is valid but the endpoint or resource they’re asking for doesn’t exist. This might be because the file has since been deleted, but make sure this isn’t caused by an HTTP/HTTPS error.

429 Too Many Requests

This occurs when the same user is trying to call the API too many times in quick succession. After a number of high-profile DDoS attacks over the past decade, web services are keeping a close eye on who’s accessing their server and how often.

This rate-limiting is similar to what you’d find on any domain or other big sites. Web hosting providers like Cloudflare handle DDoS protection for domains hosted on their servers. For APIs, these protections have to be built-in.

5xx API Errors

Status codes beginning with 5 are all server errors, potentially on your end. If that’s the case, make sure your error messages provide some help or reassurance to the user. This could be contact information or a page with live uptime/downtime information.

API providers can avoid bad error messages with just a little bit of tailoring and error handling. Go beyond the error code and use clear, succinct messages that link back to the documentation.

Software providers should have created a target consumer profile of the developers who’ll be using their API. Error messages can and should be tailored to the kinds of digital tasks they’ll be trying to accomplish.

Take a look at this error message from Twilio, whose API allows developers to place a VoIP call.

“`

{

“code”: 21211,

“message”: “The ‘To’ number 5551234567 is not a valid phone number.”,

“more_info”: “https://www.twilio.com/docs/errors/21211”,

“status”: 400

}

“`

Beyond the standard 400 status, there’s a custom error code “21211” at the top. The message even refers to the specific virtual telephone number which is causing the issue. It refers the user to the page in their documentation where they discuss the 21211 issue.

Bad error messages can be a huge stumbling block for developers trying to integrate an API into their product-driven company. An easy integration process is critical to an API’s success. One of the first things many people hear about Stripe is how easy it is to just paste in a few lines of code and get payments moving. Good error messages, then, aren’t just important for functionality, they’re also a great marketing asset for your API.

3. Method Mixups

APIs and their users can encounter errors when they get their request methods mixed up. If the user sends a POST request that gets redirected and returned as a GET request, this could cause a frustrating error that isn’t their fault.

Another cause of method errors is unclear documentation. This can happen when a section of your documentation doesn’t explain which methods are required or uses the wrong verb entirely. (Watch out for using the word “get” and GET interchangeably. Make sure your docs’ formatting is clear and save yourself a customer support email.)

4. Missing Content-Type/Accept headers

Most API calls have at least two pieces of header data: Content-Type and Accept. These headers help two parties – such as two APIs – negotiate which kind of data is being sent over and which kinds will be accepted in return. Like any negotiation, these can break down.

Some APIs will accept requests that don’t have these headers if there’s no reason to be so strict. Each line of code introduces possible errors into the software, so cloud PBX providers often don’t specify a header requirement if they don’t have to. But in commercial APIs with security concerns, developers will ask for specific Content-Type and Accept headers. This allows them to tightly control what’s allowed into their system and what’s allowed to move through.

Content-Type tells the API the format of the date you’re sending over, and Accept tells the API what to send back. APIs might only require you have something in the headers, some will accept specific types and reject others.

This information should be specified in the documentation where it’s not a security risk to do so, but certain developer tools can trip users up. Consider curl, which automatically includes the default Accept header in requests. API providers can anticipate these tooling quirks, modifying the request or sending a specific error message.

5. Authorization Errors

This is a common API error and often a very simple one. APIs using the OAuth 2 security protocol require an extra piece of header data to process requests. This is the “authorization” header, containing the private key required for the API to process the request.

It’s a common error to send an “authentication” header instead. This is because developers and documentation often talk about authentication and authorization interchangeably. But even if the header is correctly labeled as “authorization”, confusing formatting errors can trip people up.

Make sure OAuth 2 API requests are formatted like so, with the “Bearer” flag before the private key:

“`

Authorization: Bearer {your_api_key_here}

“`

Username and password pairs should be formatted like “username:password”. But even if the API request doesn’t require a password users might have to append a colon on the end. API providers could append the colon themselves, or make it clear in documentation exactly what the formatting is.

6. Data formatting errors

Even if the user is doing everything right, APIs can still spit out data in the wrong format. If the API gives users their data in HTML rather than the JSON they thought they’d asked for, this could cause a flat-out crash. Worse, their software development might happily accept the data and process it in a way that isn’t expected.

If the developer is trying to join up services to measure the conversion rate for ecommerce sites, the marketing team won’t see the code. They could spend days looking at faulty data before anyone realizes something’s not right.

We’ve mentioned request methods defaulting to GET because of a redirect. But more often this error occurs when the user hasn’t specified the Accept header correctly if at all. This might give providers a reason to be more strict about what content types they accept, even if it’s not a security risk.

API providers should also check the kinds of responses they might receive as defaults or in error. If your API has no reason to be processing HTML, you should reject that content type. This avoids issues you might run into with common tools. For example, whenever Nginx gets a request time-out, it can give you an HTML error that your API has no idea how to process.

Preventing errors explained

Preventing a lot of these common errors comes down to thorough testing. It’s also a good idea to tightly control what data your API will accept once it’s out there in the wild. In addition, API providers should put a premium on excellent api documentation and error messages.

This will help users figure issues out for themselves, but if it comes to a software for customer service, it’ll help you solve the issue faster. Once you’ve identified that flaw, it’s time to see if you can improve your docs or even abstract the whole issue away so it doesn’t happen again.