Troubleshooting API Error Codes

Whether you're a novice embarking on your first API integration project or a developer with years of experience, you will need to rely on the documentation provided and your ingenuity. HTTP status codes can give you an idea of what was going on when you made your API request. 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.

Since it’s easier to anticipate things going right, rather than things going wrong, let’s look at the 10 most common HTTP status codes that indicate an error response, either on the client or the server-side. A list of the most likely API error statuses you may encounter with Guesty’s Open API can be found in this handy table.

Client-Side Status Codes

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, and is the reason you will encounter this error with the Open API.

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 406 Not Acceptable error message, which appears when your request is correctly formatted, but has requested the response in a language other than the supported JSON.

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 (Guesty applies the same rate limits to all our customer accounts, equally).

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. Guesty API response headers include your remaining rate limits, providing you with a starting point for self monitoring. Click here for more information.

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 the scope of our Open API and its limits before designing your 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 to contact us.

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 more resources are required to be allocated to the API.

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, please contact us.

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 a 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.

Contacting Support

When a status code response doesn’t match the expected output, and you can confirm that the resources is available to you, and that your credentials and access token are valid, please contact our Customer Solutions team and provide them with the following information:

• The full URL of your request.
• The response error code and any included messages.
• The x-request-id value found in the response header.