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.

## Ensure connectivity

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

2. Your credentials are embedded in your [request](https://developers.google.com/google-ads/api/docs/concepts/call-structure#request-headers) 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).

3. Verify that you are using the correct credentials. Our
   [Quickstart guide](https://developers.google.com/google-ads/api/docs/get-started/make-first-call) 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.

## Determine 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.match_type'.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 1 }
            ]
          }
        }
      ]
    }

All our [client libraries](https://developers.google.com/google-ads/api/docs/client-libs) 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.

## Research the error

1. Refer to our [Common Errors](https://developers.google.com/google-ads/api/docs/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.

2. If our common errors documentation doesn't specifically mention the error,
   consult our [reference documentation](https://developers.google.com/google-ads/api/reference/rpc/v26/overview) and look for the error
   string.

3. Search our [support channels](https://developers.google.com/google-ads/api/support) 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.

4. Go to the [Google Ads Help Center](https://support.google.com/google-ads/) for help troubleshooting
   validation or account limit issues---the Google Ads API inherits the rules and
   limitations of the core Google Ads product.

5. [Blog posts](https://ads-developers.googleblog.com/search/label/google_ads_api) will on occasion be a good reference when
   troubleshooting your application.

6. If you encounter any errors that are not documented, contact
   [support](https://developers.google.com/google-ads/api/support/contact).

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

## Locate 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 [`fieldPathElements`](https://developers.google.com/google-ads/api/reference/rpc/v26/ErrorLocation#field_path_elements%5B%5D) in the
[`location`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsError#location) field of the [`GoogleAdsError`](https://developers.google.com/google-ads/api/reference/rpc/v26/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": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "keyword" }
            ]
          }
        }
      ]
    }

When you troubleshoot an issue, you may find that your application is providing
the wrong information to the API. We strongly encourage using an integrated
development environment (IDE) debugger to set breakpoints, step through your
code line by line, and inspect the constructed request payloads before they are
sent.

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](https://protobuf.dev/reference/protobuf/google.protobuf/#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](https://developers.google.com/google-ads/api/reference/rpc/v26/overview) 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. You can
contact [support](https://developers.google.com/google-ads/api/support/contact) for assistance.

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 OAuth access token, refresh token, and customer IDs.
- 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.
- [`request-id`](https://developers.google.com/google-ads/api/docs/best-practices/understand-api-errors#request-id). This enables Google Developer Relations team members to locate your request if made against the production environment. We recommend logging the `request-id` included in response headers or exceptions that encapsulate response errors, as well as more context than the `request-id` alone.
- Additional information, such as the runtime or interpreter version and the platform, can also be useful when troubleshooting.

## Fix 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).

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