Things don’t always go well when using an API for the first time, especially if you’re a beginner and it’s your first time integrating an API into another system. Often documentation is lacking in terms of errors, since it’s easier to anticipate things going right, than things going wrong.

In HTTP, many status codes can give you an idea of what was going on when you called an API. The standardized status codes go from 100 to 511, and all have different meanings, but only the ones from 400 to 511 are about errors. See them here in this handy table.

Let’s look at the 10 most common HTTP status codes that indicate an error, either on the client or the server.

Client-Side Errors

The 4XX group of status codes is usually related to client-side errors, but changes on the API can also cause them. Here are the 5 most common errors and how to solve them:

404 Not Found

This is by far the most common error code you can get. It indicates that the URL you used in your request doesn’t exist on the server.

While this is a 4XX error, which usually means something on the client-side is wrong, this can also indicate a server problem. Sometimes API URLs change after a version update, but sometimes they change because something on the server went wrong.

The best course of action is to check if you don’t have a typo in your client code before checking if the API has issues.

401 Unauthorized

This status code means you haven’t yet authenticated against the API. The API doesn’t know who you are and so it won’t serve you.

For most APIs, you need to sign up and get an API key. This key is then used inside an HTTP header field when you send a request, telling the API who you are.

403 Forbidden

The forbidden status indicates that you don’t have permission to request that URL. The difference to the Unauthorized status is that you’re authenticated, but the user or role you’re authenticated for isn’t permitted to make the request.

This also occurs when you have an authentication issue, like when using the wrong API key or trying to access features your subscription plan doesn’t allow for.

400 Bad Request

The bad request status is one of the most generic error messages. It implies that you did something wrong in your request. If no additional error information is given in the response body, you have to check the docs. You could be missing a query or body field in the request, or a header could be wrong. It could also be that some of your request data might have the incorrect format.

429 Too Many Requests

Most API subscription plans have limits: the cheaper the plan, the fewer requests per second are allowed for your API key. If you’re sending too many requests in a short amount of time, consider throttling them in your client. This status can also indicate that you hit a daily, weekly, or monthly limit on your account.

Sometimes an API sounds like a right fit until you see the limits, and suddenly it doesn’t work for your use case anymore. Check what’s part of your API subscription before integrating; otherwise, you may run into problems weeks or months after integrating the API.

Server-Side Errors

The 5XX group of status codes is usually related to server-side errors, but an invalid request that should respond with a 4XX can also lead to a 5XX error if not caught correctly on the server. Here are the 5 most common errors and how to fix them:

500 Internal Server Error

This status can mean anything really, but it usually indicates the API server crashed. It could have been caused by something request-related. Double-check the docs to make sure you did everything right: query fields, body fields, headers, format, etc.

If that didn’t fix the problem, it might also have been related to an API update that introduced buggy code, or data the API loaded from an upstream service. In that case, your only cause of action is contacting API support.

502 Bad Gateway

This status tells you that the server you were calling wasn’t the actual API server, but a gateway or proxy. The proxy server tries to call the API server in your name. The status also indicates that the API server didn’t answer. This could be related to a network problem, or simply because the API server crashed or was down for maintenance.

This problem is usually just temporary and should be solved by the API provider, but you have to contact support if it persists.

503 Service Unavailable

The service unavailable status means the server is overloaded. Too many API requests were sent and now the API can’t handle any more of them. This problem solves itself when clients send fewer requests, but it could also mean that the API provider didn’t plan enough resources for all of its customers.

If it fits your use case, you can make your client more resilient to this error by waiting to send more requests. But if the error keeps showing up, you have to contact the API provider.

504 Gateway Timed Out

Like the bad gateway status, this one tells you that the server you were calling is a proxy for the real API server. This time the problem is that the API server didn’t answer promptly.

This could be related to high network latency between the proxy and the API server. It could also mean that the API server takes too long to process your request.

To solve this problem, check if your request’s content could be related to that timeout. If you are requesting too much data or a calculation that takes too long, you should try and cut it down.

If you think your request is reasonable and the status doesn’t go away, contact support.

501 Not Implemented

The not implemented status is related to the HTTP method you used to request an URL. You can try a different method to make the request.

Usually, requests with a wrong method simply result in a 404 not found status. A not-implemented status implies that the method isn’t implemented “yet.” The API creator can use this status to tell the clients that this method will be available to them in the future.

Monitoring HTTP Error Codes

Tracking these errors manually quickly becomes tedious, and allows the possibility of an error.

API analytics can provide monitoring and notification capabilities, so you can keep abreast of any HTTP status code errors automatically and gain deep insights from error status code trends. These tools can be built in-house or bought. Below is an example of an API analytics tool documenting HTTP error trends over time.

If the analytics tool tracks API calls with the user identity, it makes it even easier to locate problems and solve them rapidly. 

Summary

Undoubtedly you’ll see many error codes when using APIs, but most have reasonable fixes. Some are related to server-side errors and some to client-side errors, where often one can cause the other.

Always try to read the docs thoroughly, so you don’t forget something while integrating. If things are simply broken, contact the API provider.

In some cases, the API provider won’t ever fix an issue and you’ll have to find a workaround. If you’re using a popular API you can also search the web, especially StackOverflow, to find a fix for your problem.