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 happened when you made your API request. The standardized status codes range from 100 to 511; each has a different meaning, but only those from 400 to 511 indicate an error response.

Since it's easier to anticipate things going right than going wrong, let's look at the 10 most common HTTP status codes that indicate an error response, either on the client or 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 the origin server. While this is a 4XX error, which usually indicates a client-side issue, it 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 in an HTTP header field when you send a request, identifying you to the API.

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, such as using the wrong API key or trying to access features your subscription plan doesn't allow, which is why 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 parameter, a field in the request body, or an incorrect header field. 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 requests a 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 too quickly, consider throttling them in your client. This response can also indicate that you hit a per-second, per-minute, per-hour, or per-day 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 integration, or you may run into problems weeks or months after integration.

Server-Side Status Codes

The 5XX group of status codes usually returns 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 an issue with 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 due to a network issue or because the API server crashed or was down for maintenance.

A "bad gateway" error is usually temporary and should be resolved by the API provider, but you should contact support if it persists.

503 Service Unavailable

The 503 Service Unavailable status indicates a server error. Too many API requests were sent, and the API can't handle any more. This problem resolves when clients send fewer future requests, but it could also indicate that more resources need 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 to reduce it.

If you think your request is reasonable and the status still hasn't changed, 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 returns a 404 Not Found status. A not-implemented status indicates that the method hasn't been implemented yet. The API creator can use this status to inform clients that this method will be available in future requests.

Contacting Support

When a status code response doesn't match the expected output, and you can confirm that the resource is available to you, and that your credentials and access token are valid, please contact our Customer Experience 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.