Solucionar erros de API

Quando você envia uma solicitação à API Google Ads, ela pode falhar por vários motivos. Por exemplo, você pode fornecer um argumento inválido ou sua conta pode ter atingido o limite para criar novas campanhas. Nesses casos, a API retorna um erro para informar o que deu errado.

Neste guia, explicamos como ler e processar erros de API para que você possa criar aplicativos mais robustos.

Estrutura de erros

Se você estiver usando uma das nossas bibliotecas de cliente, os erros da API vão aparecer como exceções. Essas exceções contêm detalhes que ajudam a entender por que o erro ocorreu.

A API Google Ads retorna informações de erro em um formato padrão. Se ocorrer um erro, a resposta vai conter um objeto GoogleAdsFailure. Esse objeto contém uma lista de objetos GoogleAdsError individuais, cada um detalhando um erro específico.

Cada objeto GoogleAdsError fornece:

  • error_code: um código de erro específico que informa o tipo de erro, como AuthenticationError.NOT_ADS_USER.
  • message: uma descrição legível por humanos do motivo do erro.
  • trigger: o valor que causou o erro, como "1234".
  • location: detalhes sobre qual parte da solicitação causou o erro, como um nome de campo específico.

Além da lista de erros, GoogleAdsFailure contém um requestId, que é um identificador exclusivo da solicitação de API que resultou em um erro.

Exemplo de erro

Veja um exemplo de como um erro aparece no formato JSON. Esse erro indica que o campo name do ad_group no índice 0 está ausente na solicitação.

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

Consulte Noções básicas sobre erros de API para saber mais sobre erros de API.

Exemplos de bibliotecas de cliente

A seção a seguir mostra como lidar com erros em várias bibliotecas de cliente.

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
    );
    $errors = $googleAdsException->getGoogleAdsFailure()->getErrors();
    foreach ($errors 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 "
            f"'{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};
  }
}

Como capturar registros

Para resolver erros, capture os registros de erros retornados pelo servidor da API Google Ads e inspecione o conteúdo deles. Siga as instruções abaixo para ativar a geração de registros e capturar os registros da API.

Java

Consulte o guia de geração de registros da biblioteca de cliente Java para ver instruções.

C#

Para inicializar a geração de registros, adicione a linha abaixo ao método Main antes de fazer chamadas de API. Isso garante que a biblioteca gere registros para todas as chamadas de API feitas pelo aplicativo.

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

Consulte o guia de geração de registros da biblioteca .NET para mais opções.

PHP

É possível definir a configuração de geração de registros no arquivo google_ads_php.ini da biblioteca de cliente. Defina logLevel como NOTICE para começar a capturar os registros de erros detalhados.

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

Consulte o guia de geração de registros da biblioteca de cliente PHP para ver instruções.

Python

É possível definir a configuração de geração de registros no arquivo google-ads.yaml da biblioteca de cliente. Defina o nível de registro como DEBUG para começar a capturar os registros de erros detalhados.

Consulte o guia de geração de registros da biblioteca do Python para mais opções.

Ruby

É possível definir a configuração de geração de registros no arquivo google_ads_config.rb da biblioteca de cliente. Defina o nível de registro como INFO para começar a capturar os registros de erros detalhados.

Consulte o guia de geração de registros da biblioteca do Ruby para mais opções.

Perl

Para inicializar a geração de registros, adicione a seguinte linha ao script Perl antes de fazer chamadas de API.

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

Consulte o guia de geração de registros da biblioteca Perl para mais opções.

curl

O curl imprime as respostas com falha em stderr por padrão.

Como lidar com erros

Se você encontrar um erro, siga estas etapas:

  1. Capturar a exceção e os registros: comece capturando as exceções e, se quiser, os registros da API.
  2. Examine a lista errors: analise cada GoogleAdsError no objeto GoogleAdsFailure. O error_code e o message vão informar o que deu errado.
  3. Verifique o valor de location: o campo location pode ajudar a identificar onde o problema ocorreu na solicitação.
  4. Consulte a documentação: para códigos de erro específicos, consulte a página de erros comuns ou a referência completa de códigos do erro para mais detalhes sobre o erro e como corrigi-lo.
  5. Ajustar a solicitação: com base na mensagem de erro, corrija a solicitação de API. Por exemplo, se você vir REQUIRED_FIELD_MISSING, forneça esse campo na solicitação.
  6. Registre o request_id: se você não conseguir descobrir como resolver um erro e precisar entrar em contato com o suporte, inclua os registros completos de solicitação e resposta da solicitação com falha. Inclua o request_id. Esse ID ajuda os engenheiros do Google a localizar os detalhes da solicitação com falha nos registros do servidor da API Google Ads e investigar o problema.

Próximas etapas

  • Consulte Erros comuns para ver uma lista de problemas frequentes e as soluções deles.
  • Para técnicas mais avançadas de tratamento de erros, incluindo lógica de repetição e falha parcial, consulte Noções básicas sobre erros de API.