10 Error Status Codes When Building APIs for the First Time and How to Fix Them

Things don’t always go well when making your first API call, especially if you’re a beginner and it’s...

Things don’t always go well when making your first API call, 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 API error status codes, since it’s easier to anticipate things going right, rather than things going wrong.

HTTP status codes can give you an idea of what was going on when you made your API call. The standardized status codes go from 100 to 511, and all have different meanings, but only the status codes from 400 to 511 reflect an error response. 

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

Client-Side Status Codes

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

404 Not Found

This is by far the most common HTTP status code you can get. It indicates that the URL you used in your request doesn’t exist on the API server, or origin 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 URL paths 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 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 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.

This http status code is similar to the less common 407 Proxy Authentication Required , which means you haven’t authenticated with the proxy.

403 Forbidden

The forbidden status indicates that you don’t have permission to request that URL. You’re authenticated, but the user or role you’re authenticated for isn’t permitted to make the API 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 400 Bad Request error message is one of the most generic HTTP status codes. It implies that you did not correctly format your API request. If no additional error information is given in the response body, you have to check the docs. You could be missing a query, a field in the request body, or a header field could be wrong. It could also be that some of your request data might have incorrect syntax.

This is different from the 422 Unprocessable Entity error message, which appears when your request is correctly formatted, but cannot be processed.

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 response can also indicate that you hit a daily, weekly, or monthly limit on your account. Without implementing API analytics, it’s possible to reach these limits without receiving a push notification or email alert. 

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 Status Codes

The 5XX group of status codes usually return in response to a server error, but an invalid API call that should respond with a 4XX can also return 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 HTTP status code can mean anything really, but it usually indicates the API server crashed. It could have been caused by something related to your API call.

Double-check the docs to make sure you did everything right: query fields, body fields, headers, and format.

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 the API’s support.

502 Bad Gateway

This response 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. This error response 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.

A “bad gateway” error is usually temporary and should be solved by the API provider, but you have to contact support if it persists.

503 Service Unavailable

The 503 Service Unavailable Status indicates a server error. 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 future 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 another request. But if the error code keeps showing up, you have to contact the API provider.

504 Gateway Timed Out

Like the 502 Bad Gateway status, this response code tells you that the server you were calling is a proxy for the real API server. This time, the problem is the API server’s slow response.

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 reduce it.

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

501 Not Implemented

The 501 Not Implemented status code is related to the HTTP method you used to request an URL. You can try a different HTTP method to make the request.

Usually, an HTTP request with an inappropriate method simply results 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 future requests.

Summary

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

Always try to read the docs and API notes 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 for an API consumer. If you’re using a popular API you can also search the web for answers, especially StackOverflow, to find a fix for your error responses. Stay determined, and you’ll see your 200 ok status codes in no time.