Solucionar erros de API

Ao enviar 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 da 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 serão exibidos 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 GoogleAdsFailure objeto. 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, GoogleAdsFailure contém um requestId, que é um identificador exclusivo da solicitação de API que resultou em um erro.

Exemplo de erro

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

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

Consulte nosso guia para saber mais sobre erros da 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 solucionar problemas, capture os registros de erros retornados pelo servidor da API Google Ads e inspecione o conteúdo deles. Use as instruções a seguir para ativar o registro e capturar registros da API.

Java

Consulte o guia de registro da biblioteca de cliente Java para instruções.

C#

É possível inicializar o registro adicionando a linha a seguir no método Main antes de fazer qualquer chamada de API. Isso garante que toda 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 .NET library logging guide para outras opções.

PHP

É possível definir a configuração de registro 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 PHP para instruções.

Python

É possível definir a configuração de registro 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 registro da biblioteca Python para outras opções.

Ruby

É possível definir a configuração de registro 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 registro da biblioteca Ruby para outras opções.

Perl

Para inicializar o registro, adicione a linha a seguir no script Perl antes de fazer qualquer chamada de API.

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

Consulte o guia de registro da biblioteca Perl para outras opções.

curl

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

Como processar erros

Se você encontrar um erro, siga estas etapas:

  1. Detecte a exceção e capture os registros: comece detectando as exceções e, opcionalmente, capturando 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 do código de erro para mais detalhes sobre o erro e como corrigi-lo.
  5. Ajuste a solicitação: com base na mensagem de erro, corrija a solicitação da API. Por exemplo, se você vir REQUIRED_FIELD_MISSING, inclua 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 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 nova tentativa e falha parcial, consulte Entender erros da API Errors.
Anterior
Início rápido
Avançar
Erros comuns