处理 API 错误

当您向 Google Ads API 发送请求时，请求可能会因各种原因而失败。例如，您可能会提供无效的实参，或者您的账号可能已达到创建新广告系列的上限。在这种情况下，API 会返回错误，让您了解出了什么问题。

本指南介绍了如何读取和处理 API 错误，以便您构建更强大的应用。

错误结构

如果您使用的是我们的某个 客户端库，API 错误 会以异常的形式显示。这些异常包含详细信息，可帮助您了解错误发生的原因。

Google Ads API 以标准格式返回错误信息。如果发生 错误，响应将包含一个 GoogleAdsFailure 对象。此 对象包含一个 GoogleAdsError对象列表，每个对象都详细说明了 一个特定错误。

每个 GoogleAdsError 对象都提供以下信息：

  • error_code：一个特定的错误 代码，用于告知您错误的类型，例如 AuthenticationError.NOT_ADS_USER。
  • message：对错误发生原因的直观易懂的说明。
  • trigger：导致错误的值，例如“1234”。
  • location：有关请求的哪个部分导致错误的详细信息，例如特定字段名称。

除了错误列表之外， GoogleAdsFailure 还包含一个 requestId，它是导致错误的 API 请求的唯一标识符。

错误示例

以下示例展示了 JSON 格式的错误。此错误表示请求中缺少索引为 0 的 ad_group 的 name 字段。

{
  "code": 3,
  "message": "Request contains an invalid argument.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.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"
    }
  ]
}

如需详细了解 API 错误，请参阅我们的指南。

客户端库示例

以下部分展示了如何在各种客户端库中处理错误。

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};
  }
}

如何捕获日志

如需排查错误，请捕获 Google Ads API 服务器返回的错误日志并检查其内容。按照以下说明启用日志记录并捕获 API 日志。

Java

如需相关说明，请参阅 Java 客户端库日志记录 指南。

C#

您可以在发出任何 API 调用之前，通过在 Main 方法中添加以下行来初始化日志记录。这样可确保库为应用发出的所有 API 调用生成日志。

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);

如需了解其他选项，请参阅 .NET 库日志记录 指南。

PHP

您可以在客户端库的 google_ads_php.ini 文件中设置日志记录配置。将 logLevel 设置为 NOTICE，以开始捕获详细的错误日志。

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

如需相关说明，请参阅 PHP 客户端库日志记录 指南。

Python

您可以在客户端库的 google-ads.yaml 文件中设置日志记录配置。将日志记录级别设置为 DEBUG，以开始捕获详细的错误日志。

如需了解其他选项，请参阅 Python 库日志记录 指南。

Ruby

您可以在客户端库的 google_ads_config.rb 文件中设置日志记录配置。将日志记录级别设置为 INFO，以开始捕获详细的错误日志。

如需了解其他选项，请参阅 Ruby 库日志记录指南 。

Perl

如需初始化日志记录，请在发出任何 API 调用之前，在 Perl 脚本中添加以下行。

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

如需了解其他选项，请参阅 Perl 库日志记录指南 。

curl

默认情况下，curl 会将失败的响应输出到 stderr。

如何处理错误

如果您遇到错误，请按照以下步骤操作：

  1. 捕获异常并捕获日志：首先捕获 异常，并选择性地捕获 API 日志。
  2. 检查 errors 列表：查看 GoogleAdsFailure 对象中的每个 GoogleAdsError。The error_code 和 message 会告知您出了什么问题。
  3. 检查 location 值：location 字段可帮助您找出请求中出现问题的位置。
  4. 查阅文档：对于特定的错误代码，请查看常见 错误页面或完整错误代码 参考，详细了解错误以及 如何修复错误。
  5. 调整请求：根据错误消息，更正 API 请求。例如，如果您看到 REQUIRED_FIELD_MISSING，请确保在请求中提供该字段。
  6. 记录 request_id：如果您无法找出解决 错误的方法，并且需要与支持团队联系，请提供失败 请求的完整请求和响应日志。请务必提供 request_id。此 ID 可帮助 Google 工程师在 Google Ads API 服务器日志中找到失败请求的详细信息，并调查您的问题。

后续步骤

  • 如需查看常见问题及其解决方案的列表，请参阅常见错误。
  • 如需了解更高级的错误处理技术，包括重试逻辑和 部分失败，请参阅了解 API 错误。
上一页
快速入门
下一页
常见错误