Solucionar erros de API

Quando você envia uma solicitação para a 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 de criação de novas campanhas. Nesses casos, a API retorna um erro para informar o que deu errado.

Este guia explica como ler e processar erros de API para que você possa criar aplicativos mais robustos.

Estrutura de erro

Se você estiver usando uma das nossas bibliotecas de cliente, os erros da API serão exibidos como exceções. Essas exceções contêm detalhes que ajudam você 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:

Além da lista de erros, o 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á faltando na solicitação.

{
  "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"
    }
  ]
}

Consulte nosso guia para saber mais sobre erros de API.

Exemplos de bibliotecas de cliente

A seção a seguir mostra como processar 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
    );
    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};
  }
}

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 o registro em log e capturar registros da API.

Java

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

C#

Para inicializar o registro, adicione a seguinte linha ao método Main antes de fazer qualquer chamada 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 o 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 registro da biblioteca de cliente do PHP para 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 geração de registros como DEBUG para começar a capturar os registros de erros detalhados.

Consulte o guia de geração de registros da biblioteca Python para outras 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 geração de registros como INFO para começar a capturar os registros de erros detalhados.

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

Perl

Para inicializar o registro, adicione a seguinte linha ao script Perl antes de fazer qualquer chamada 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

Por padrão, o curl imprime as respostas com falha em stderr.

Como processar erros

Se você encontrar um erro, siga estas etapas:

  1. Capturar a exceção e os registros: comece capturando as exceções e, opcionalmente, os registros da API.
  2. Examine a lista errors: analise cada GoogleAdsError no objeto GoogleAdsFailure. Os error_code e message vão informar o que deu errado.
  3. Verifique o valor de location: o campo location pode ajudar você a identificar onde o problema ocorreu na sua solicitação.
  4. Consulte a documentação: para códigos de erro específicos, confira a página de erros comuns ou a referência completa de códigos de erro para mais detalhes sobre o erro e como corrigi-lo.
  5. Ajuste sua solicitação: com base na mensagem de erro, corrija sua solicitação de API. Por exemplo, se você vir REQUIRED_FIELD_MISSING, forneça esse campo na sua solicitação.
  6. Registre o request_id: se você não conseguir 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 seu problema.

Próximas etapas

  • Consulte Erros comuns para conferir 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 Entender erros da API.
Anterior
Início rápido
Avançar
Erros comuns