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:

• Your API credentials
• The API host URL
• The API port
• The API call URL

Verify your API credentials

If your Looker API endpoint isn’t reachable, the first step is to verify that your API credentials are correct. To view your API credentials:

1. In Looker, access the Admin panel by selecting the Admin option in the left navigation panel.
2. In the left panel of the Admin page, scroll down and click Users.
3. Search for your username in the user list, and click on it to edit your user page.
4. Click on Edit API Keys. You can see the Client ID, and you can click on the eye icon to view the Client Secret for each API key you have configured. Verify that your API credentials match the credentials you are using in your script.

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). To view the API host URL:

1. Access the Admin panel by selecting the Admin option in the left navigation panel.
2. Click API in the Admin panel.

3. View the API Host URL.

   If the API Host URL field is blank, your Looker instance uses the default format, which is:

   https://<instance_name>.looker.com:<port>
   

You can test the API Host URL by doing the following:

1. 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.)

2. Enter your API Host URL followed by /alive. For example, if your API Host URL is https://company.api.looker.com, enter:

   https://company.api.looker.com/alive
   

   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 443:

   https://<instance_name>.looker.com:443/alive
   

   For instances hosted on AWS that were created before 07/07/2020, the default Looker API path uses port 19999:

   https://<instance_name>.looker.com:19999/alive
   

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 200:

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:

• Proxies
• Load balancers
• Firewalls

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 Explorer, on Looker’s Developer Portal, or from the API Reference documentation.

For example, the API 4.0 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:

https://docsexamples.dev.looker.com:443/api/4.0/running_queries

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

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

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:

https://<your-looker-hostname>:<port>/api/3.0/login
https://<your-looker-hostname>:<port>/api/3.1/login

If using a Swagger codegen API or a Looker SDK, ensure your base_url value is correct:

• For a Swagger codegen client, the base_url should be one of the following, depending on the API version in use:
  • https://<your-looker-hostname>:<port>/api/3.0/
  • https://<your-looker-hostname>:<port>/api/3.1/

• 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 application/json.

Note that using a Looker SDK will automatically deal with this concern for you.