Troubleshooting

Video: Check out the error handling talk from the 2019 workshop

Errors can be caused by an incorrect environment setup, a bug in your software, or invalid input from a user. No matter the source, you will need to troubleshoot the issue and either fix your code or add logic to handle the user error. This guide discusses some best practices when troubleshooting errors from the Google Ads API.

Ensuring connectivity

Make sure you have access to the Google Ads API and a correct setup. If your response returns any HTTP errors, make sure you address those carefully and that you are reaching the services you intend to use from your code.
Your credentials are embedded in your request in order for the services to authenticate you. Familiarize yourself with the structure of Google Ads API requests and responses, especially if you are going to handle calls without using the client libraries. Each client library is shipped with specific instructions on how to include your credentials in the config file (consult the client library's README).

Verify that you are using the correct credentials. Our Quickstart takes you through the process of acquiring the correct set you need. For example, the following response failure shows that the user has sent invalid authentication credentials:

{
  "error": {
    "code": 401,
    "message": "Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential. Visit https://developers.google.com/identity/sign-in/web/devconsole-project.",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "Authentication error: 2"
      }
    ]
  }
}

If you've followed these steps and are still having issues, it's time to dive into troubleshooting the Google Ads API errors.

Determining the problem

The Google Ads API generally reports errors as a JSON failure object, containing a list of errors in the response. These objects provide an error code as well as a message elaborating on why it occurred. They are your first signals of what the problem might be.

{
  "errors": [
    {
      "errorCode": { "fieldMaskError": "FIELD_NOT_FOUND" },
      "message": "The field mask contained an invalid field: 'keyword/matchtype'.",
      "location": { "operationIndex": "1" }
    }
  ]
}

All our client libraries throw exceptions that encapsulate errors in the response. Capturing these exceptions and printing out the messages in a log or a troubleshooting screen is a great way to start. Integrating this information with the other logged events in your application offers a good overview of what might be triggering the problem. Once you've identified the error in the logs, you'll need to figure out what it means.

Researching the error

Refer to our Common Errors documentation, which covers the most frequently encountered errors. It describes the error message, relevant API references, and how to avoid or handle the error.
If our common errors documentation doesn't specifically mention the error, consult our reference documentation and look for the error string.
Search our support channels to gain access to other developers sharing their experiences with the API. Someone else may have run into—and solved—the problem you are having.
If you encounter any errors that are not documented, bring this to our attention on the forum.
Go to the Google Ads Help Center for help troubleshooting validation or account limit issues—the Google Ads API inherits the rules and limitations of the core Google Ads product.
Blog posts will on occasion be a good reference when troubleshooting your application.

After researching the error, it's time to determine the root cause.

Locating the cause

Check the exception message to determine the cause of the error. After looking at the response, check the request for a possible cause. Some Google Ads API error messages include a fieldPathElements in the location field of the GoogleAdsError, indicating where in the request the error occurred. For example:

{
  "errors": [
    {
      "errorCode": {"criterionError": "CANNOT_ADD_CRITERIA_TYPE"},
      "message": "Criteria type can not be targeted.",
      "trigger": { "stringValue": "" },
      "location": {
        "operationIndex": "0",
        "fieldPathElements": [ { "fieldName": "keyword" } ]
      }
    }
  ]
}

When troubleshooting an issue, it may be that your application is providing the wrong information to the API. We strongly encourage the use of an Interactive Development Environment (IDE) such as Eclipse (a free and open source IDE which is primarily used to develop Java, but has plugins for other languages) to aid you in debugging. It lets you set breakpoints and step through your code line by line.

Double-check to make sure the request matches your application inputs (for example the Campaign's name might not be making it to the request). Make sure you send a field mask that matches the updates you want to make--the Google Ads API supports sparse updates. Omitting a field from the field mask in a mutate request indicates the API should leave it alone. If your application retrieves an object, makes a change, and sends it back, you may be writing to a field that does not support updating. Check the field's description in the reference documentation to see if there are any restrictions on when or if you can update the field.

How to get help

It's not always possible to identify and solve the problem on your own. Asking on the forum exposes your question to thousands of developers who may have had to deal with the same issue.

Try to include as much information as you can in your queries. Recommended items include:

Sanitized JSON request and response. Make sure to remove sensitive information such as your developer token or AuthToken.
Code snippets. If you are having a language-specific problem or are requesting help working with the API, include a snippet of code to help explain what you are doing.
RequestId. This enables Google Developer Relations team members to locate your request if made against the production environment. We recommend registering in your logs the requestId included as a property in the exceptions that encapsulate response errors, as well as more context than requestId alone.
Additional information, such as runtime/interpreter version and platform can also be useful when troubleshooting.

Fixing the problem

Now that you've figured out the problem and come up with a solution, it's time to make your change and test the fix against a test account (preferred) or production (if the bug only applies to data in a specific production account).

Consider Sharing

If you have posted a question in the forum regarding an error that hadn't been surfaced there before and you have found the solution, consider adding it to the thread. Next time a developer has the same problem they'll be able to solve it right away.

Next Steps

Now that you've solved this problem, did you notice any ways to improve your code to avoid this in the first place?

Creating a good set of unit tests helps improve code quality and reliability considerably. It also speeds up the process of testing new changes to ensure they didn't break previous functionality. A good error handling strategy is also key in surfacing all the necessary data for troubleshooting.

System limits

Testing