Errors

In this guide, we will discuss how to handle errors and what to do when something goes wrong while using the Cocktail API. Mistakes can happen, and often they are due to issues on the client side rather than the API itself. Let's review some common status codes and error types you might encounter.

You can determine if your request was successful by checking the status code in the API response. If the response indicates an error, you can use the error type and message to understand what went wrong and perform basic troubleshooting before reaching out for support.

Before contacting support with an error, please remember that most reported errors are typically due to issues on the client side. Carefully review your request and code before seeking assistance.

Status Codes

Here is a list of the different categories of status codes returned by the Cocktail API. Use these codes to understand if a request was successful or if there was an issue.

Name
2xx
Description
A 2xx status code indicates a successful response. For example, a 200 OK means your request was successful, and the data you requested is included in the response.
Name
4xx
Description
A 4xx status code indicates a client error — this means there is an issue with your request. Common examples include:
- 400 Bad Request: The request could not be understood or was missing required parameters.
- 401 Unauthorized: Lookup Endpoints credentials are missing or invalid.
- 404 Not Found: The requested resource could not be found.
Name
5xx
Description
A 5xx status code indicates a server error — these are issues on the API server side, and typically you will not see these unless there is a problem with the API itself.

Error Types

Whenever a request is unsuccessful, the Cocktail API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most error messages are designed to be helpful and actionable.

Here is a list of the two error types supported by the Cocktail API — use these to understand what you might have done wrong.

Name
api_error
Description
This indicates a problem on the API side, though such errors are rare. They suggest that something went wrong on the server that is out of your control.
Name
invalid_request
Description
This indicates an issue with your request, such as missing or invalid parameters. This is the more common error type and usually requires you to adjust your request.

Error response

{
  "type": "api_error",
  "message": "An unexpected error occurred. Please try again later.",
  "documentation_url": "https://your-api-docs-url/errors/api_error"
}