This page has troubleshooting procedures for the following problems that people may encounter with the Looker API:
- API endpoint isn’t reachable
- Validation (422) errors
- Not Found (404) errors
- Bad Request (400) errors
- API calls hang
- Invalid encoding errors
API Endpoint Isn’t Reachable
If you can’t reach an API endpoint, you can verify:
Verify Your API Credentials
If your Looker API endpoint isn’t reachable, the first step is to verify that your API credentials are correct:
- In Looker, click on Admin at the top right of the window.
- In the left panel of the Admin page, scroll down and click API.
- On the API page, click the View API Docs link to open the interactive API Explorer. (See the Getting Started with the Looker API documentation page for information on the interactive API Explorer.) If the API Explorer does not open, you may need to verify the API port.
- In the API Explorer, enter the API3 client ID and client secret. (See the Users documentation page for information on setting up API3 keys.)
- Click Log In.
- Scroll down to the User > Manage Users section and click the arrow to expand it.
- Click on the
me()API call to expand it.
- Click the Try it out button.
This should produce a
200 Response Code with a Response body that starts with something like this:
In the API Explorer, it looks something like this:
If you see the expected JSON output, then your API credentials are working. Try to use these exact credentials to reach your API endpoint. If you still cannot reach the API endpoint using these credentials, next verify that you’re using the correct API URL.
Verify the API URL
Another common problem in reaching an API endpoint is an incorrect API host URL. Most Looker instances use the default URL for the API. However, Looker installations using an alternate API path or Looker installations located behind a load balancer (for example, a cluster configuration) or any other proxy might not use the default URL. If this is the case, the API host URL must indicate the user-facing API host name and port.
Looker admins can see the API host URL in the API admin settings (described in more detail on the Admin Settings - API documentation page):
- Click Admin to open the Admin menu.
- Click API in the Admin panel.
View the API Host URL.
If the API Host URL field is blank, your Looker instance uses the default format, which is:
You can test the API Host URL by doing the following:
- Open a browser and open the browser console. (This link might be helpful if you need to know how to open a console for your browser.)
Enter your API Host URL followed by
/alive. For example, if your API Host URL is
If your API Host URL field is blank, use the default API URL. For example, for instances hosted on Google Cloud Platform (GCP), Microsoft Azure, and instances hosted on Amazon Web Services (AWS) that were created on or after 07/07/2020, the default Looker API path uses port
For instances hosted on AWS that were created before 07/07/2020, the default Looker API path uses port 19999:
If the API host URL is correct, this URL will result in a blank web page, and not an error page:
You can also verify that you’ve reached the API by looking at the network response in the browser console. The network response should be
If these checks fail, the problem may be that you are calling the API incorrectly or that you have other errors in your code. Check your API calls and the code in your script. If those are correct, see the next section about verifying your port.
Verify the API Port
If the above checks fail and you have a customer-hosted Looker deployment, it is possible that the API port needs to be opened on the network infrastructure.
The API port should forward to the Looker server. For customer-hosted Looker deployments, ask your network administrator to check the API port settings. The API port default setting is
443 for instances hosted on GCP, Azure, and instances hosted on AWS that were created on or after 07/07/2020. For instances hosted on AWS that were created before 07/07/2020, the default port setting is
19999. The API port should have the same configuration settings as the Looker instance port (
9999 by default). Your network administrator should verify that the following settings are the same for the API port as they are for your Looker instance port:
- Load balancers
Verify the API Call URL
Another thing to check is that you have the correct URL for your API call. The format of an API endpoint URL is:
<API Host URL>/api/<API version>/<API call>
If you are using the default API host URL, the format of an API endpoint URL is:
https://<instance_name>:<port>/api/<API version>/<API call>
You can get the URL format for API endpoints from the API Reference or from the interactive API documents.
For example, the API 3.1 Reference gives the following relative path for the Get All Running Queries endpoint:
So the full API endpoint URL for the
docsexamples.dev.looker.com Looker instance is this:
Validation Errors (422 Errors)
Validation errors occur when something in the request failed the data checks performed. The request has one or more of the following types of errors (the error response will specify the exact errors):
- Missing fields: There’s a required parameter that was not provided (the error response will say which field is missing).
- Invalid: The value provided doesn’t match an existing value or the value is not in the correct format. For example, if you try to create a Look and the query ID you provide in the API call doesn’t match an existing query you will get a validation error.
- Already exists: The API call is attempting to create an object with an ID or name that is already present on your Looker instance. For example, database connection names must be unique. If you try to create a new database connection that uses the name of an existing connection, you will get a validation error with the code
See the error response message for details on which fields may have been missing or required, or which fields may have invalid values. The response message will provide all of the validation errors at the same time. So if you have missing fields and also incorrect fields, the error response will list all of the problems with your API call.
Here is an example response:
In this case, the API call was missing the required
dialect field and also had an invalid value given in the
Not Found Errors (404 Errors)
A 404 Not Found error is the default error if anything goes wrong, usually with things like permissions. The response message for a 404 error provides minimal, if any, information. This is intentional, since 404 errors are shown to people with incorrect login credentials or insufficient permissions. Looker does not want to provide specific information in 404 response messages, since this information could be used to map out the “attack surface” of our API.
If API login attempts are returning 404 errors, it’s most likely because your API3 client ID or client secret isn’t valid (see [this section](#verify_creds above)). The API login REST endpoint is one of the following, depending on the API version in use:
If using a Swagger codegen API or a Looker SDK, ensure your
base_url value is correct:
- For a Swagger codegen client, the
base_urlshould be one of the following, depending on the API version in use:
For Looker SDK implementations that use a
looker.ini, the values should be:
# api_version should be either 3.0 or 3.1 api_version=3.0 base_url=https://<your-looker-hostname>:<port>
You can also get a 404 error after you log in. If you’re logged in and you get a 404 error, that means you don’t have permissions for the API command you just called.
Bad Request Errors (400 Errors)
A 400 Bad Request error indicates that the data provided in an API call is unrecognizable. The culprit is often broken or invalid JSON, perhaps a parse error. For the most part, 400 errors have already passed authentication, so the error response message will provide more specific information about the error.
Method Not Found Errors
If you get a Method Not Found error, such as
method not found: all_looks(), the first thing to check is your API version. There are several API calls that are new in API 3.1 or were removed in API 3.1. See this article for the list of updates from API 3.0 to API 3.1.
API Result Is Nonsensical Text
If the API returns a response of garbled text, it is likely that you’re seeing the binary content of a PDF, PNG, or JPG file. Some HTTP REST libraries assume that API responses will be text files and so other types of files are displayed as binary text.
In this case, you need to be sure that your HTTP REST library handles the API response as binary data, not as text. In some cases, this might mean setting a flag on the API call to tell the HTTP REST library that it’s a binary result, or it might mean handling the result in a special way, like as a stream of bytes or as an array of bytes, instead of assigning the result to a string variable.
API Calls Hang
If you are able to open the API Explorer but your API calls hang, verify that your Looker instance’s API Host URL setting is either blank or set correctly. Looker admins can see the API host URL in Looker’s API admin settings (described on the Admin Settings - API documentation page).
Invalid Encoding Errors
If you receive an encoding error when attempting to make an API call, you may need to set the proper
Content-Type in your header during the request. HTTP protocol standards require that any POST, PUT, or PATCH request contain a
Content-Type header. Since the Looker API uses JSON throughout, the
Content-Type header should be set to
Note that using a Looker SDK will automatically deal with this concern for you.