Handle API errors

When you send a request to the Google Ads API, it might fail for various reasons. For example, you might provide an invalid argument, or your account might have reached its limit for creating new campaigns. In such cases, the API returns an error to let you know what went wrong.

This guide explains how to read and handle API errors so you can build more robust applications.

Error structure

If you are using one of our client libraries, API errors are surfaced as exceptions. These exceptions contain details that help you understand why the error occurred.

The Google Ads API returns error information in a standard format. If an error occurs, the response will contain a GoogleAdsFailure object. This object contains a list of individual GoogleAdsError objects, each detailing a specific error.

Each GoogleAdsError object provides:

  • error_code: A specific error code that tells you the type of error, such as AuthenticationError.NOT_ADS_USER.
  • message: A human-readable description of why the error occurred.
  • trigger: The value that caused the error, like "1234".
  • location: Details on which part of the request caused the error, such as a specific field name.

In addition to the list of errors, GoogleAdsFailure contains a requestId, which is a unique identifier for the API request that resulted in an error.

Example error

Here is an example of what an error looks like in JSON format. This error indicates that the name field of the ad_group at index 0 is missing from the request.

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v22.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "requestError": "REQUIRED_FIELD_MISSING"
          },
          "message": "Required field is missing",
          "location": {
            "fieldPathElements": [
              {
                "fieldName": "ad_group",
                "index": 0
              },
              {
                "fieldName": "name"
              }
            ]
          }
        }
      ],
      "requestId": "unique_request_id_12345"
    }
  ]
}

Refer to our guide to learn more about API errors.

Client library examples

The following section shows how to handle errors in various client libraries.

Java

try {
  // Make an API call.
  ...
} catch (GoogleAdsException gae) {
  // GoogleAdsException is the base class for most exceptions thrown by an API request.
  // Instances of this exception have a message and a GoogleAdsFailure that contains a
  // collection of GoogleAdsErrors that indicate the underlying causes of the
  // GoogleAdsException.
  System.err.printf(
      "Request ID %s failed due to GoogleAdsException. Underlying errors:%n",
      gae.getRequestId());
  int i = 0;
  for (GoogleAdsError googleAdsError : gae.getGoogleAdsFailure().getErrorsList()) {
    System.err.printf("  Error %d: %s%n", i++, googleAdsError);
  }
}

C#

try
{
    // Make an API call.
    ...
}
catch (GoogleAdsException e)
{
    Console.WriteLine($"Request with ID '{e.RequestId}' has failed.");
    Console.WriteLine("Google Ads failure details:");

    foreach (GoogleAdsError error in e.Failure.Errors)
    {
        Console.WriteLine($"{error.ErrorCode}: {error.Message}");
    }
}

PHP

try {
  // Make an API call.
  ...
} catch (GoogleAdsException $googleAdsException) {
    printf(
        "Request with ID '%s' has failed.%sGoogle Ads failure details:%s",
        $googleAdsException->getRequestId(),
        PHP_EOL,
        PHP_EOL
    );
    foreach ($googleAdsException->getGoogleAdsFailure()->getErrors() as $error) {
        /** @var GoogleAdsError $error */
        printf(
            "\t%s: %s%s",
            $error->getErrorCode()->getErrorCode(),
            $error->getMessage(),
            PHP_EOL
        );
    }
}

Python

try:
    # Make an API call.
    ...
except GoogleAdsException as ex:
    print(
        f"Request with ID '{ex.request_id}' failed with status "
        f"'{ex.error.code().name}' and includes the following errors:"
    )
    for error in ex.failure.errors:
        print(f"\tError with message '{error.message}' and code '{error.error_code}'.")

Ruby

begin
    # Make an API call.
    ...
rescue Google::Ads::GoogleAds::Errors::GoogleAdsError => e
    puts "API call failed with request ID: #{e.request_id}"
    e.failure.errors.each do |error|
        puts "\t#{error.error_code}: #{error.message}"
    end
end

Perl

# Try sending a mutate request to add the ad group ad.
...
if ($response->isa("Google::Ads::GoogleAds::GoogleAdsException")) {
  printf "Google Ads failure details:\n";
  foreach my $error (@{$response->get_google_ads_failure()->{errors}}) {
    printf "\t%s: %s\n", [keys %{$error->{errorCode}}]->[0], $error->{message};
  }
}

How to capture logs

To troubleshoot errors, capture the error logs returned by the Google Ads API server and inspect their contents. Use the following instructions to enable logging and capture API logs.

Java

Refer to the Java client library logging guide for instructions.

C#

You can initialize logging by by adding the following line in your Main method before making any API calls. This ensures that all the library generates logs for all the API calls made by your application.

using Google.Ads.GoogleAds.Util;
...

// Detailed logs.
TraceUtilities.Configure(TraceUtilities.DETAILED_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/details.log", System.Diagnostics.SourceLevels.All);

// Summary logs.
TraceUtilities.Configure(TraceUtilities.SUMMARY_REQUEST_LOGS_SOURCE,
    "/path/to/your/logs/summary.log", System.Diagnostics.SourceLevels.All);

Refer to the .NET library logging guide for additional options.

PHP

You can set the logging configuration in your client library's google_ads_php.ini file. Set the logLevel to NOTICE to start capturing the detailed error logs.

[LOGGING]
; Optional logging settings.
logFilePath = "path/to/your/file.log"
logLevel = "NOTICE"

Refer to the PHP client library logging guide for instructions.

Python

You can set the logging configuration in your client library's google-ads.yaml file. Set the logging level to DEBUG to start capturing the detailed error logs.

Refer to the Python library logging guide for additional options.

Ruby

You can set the logging configuration in your client library's google_ads_config.rb file. Set the logging level to INFO to start capturing the detailed error logs.

Refer to the Ruby library logging guide for additional options.

Perl

To initialize logging, add the following line in your perl script before making any API calls.

Google::Ads::GoogleAds::Logging::GoogleAdsLogger::enable_all_logging();

Refer to the Perl library logging guide for additional options.

curl

curl prints the failed responses to stderr by default.

How to handle errors

If you encounter an error, here are the steps to take:

  1. Catch the exception and capture the logs: Start by catching the exceptions and optionally capturing the API logs.
  2. Examine the errors list: Look at each GoogleAdsError in the GoogleAdsFailure object. The error_code and message will tell you what went wrong.
  3. Check the location value: The location field can help you pinpoint where in your request the issue occurred.
  4. Consult documentation: For specific error codes, check the common errors page or the full error code reference for more details on the error and how to fix it.
  5. Adjust your request: Based on the error message, correct your API request. For example, if you see REQUIRED_FIELD_MISSING, make sure you provide that field in your request.
  6. Log the request_id: If you are unable to figure out how to resolve an error and need to contact support), include the full request and response logs for the failing request. Ensure to include the request_id. This ID helps Google engineers locate the failing request details on the Google Ads API server logs and investigate your issue.

Next steps

  • Review Common Errors for a list of frequent issues and their solutions.
  • For more advanced error handling techniques, including retry logic and partial failure, see Understand API Errors.
Previous
Quickstart
Next
Common errors