Entender os erros da API

Este guia explica como a API Google Ads processa e comunica erros. Entender a estrutura e o significado dos erros da API é fundamental para criar aplicativos robustos que possam lidar com problemas, desde entradas inválidas até indisponibilidade temporária do serviço.

A API Google Ads segue o modelo de erro padrão da API Google, que é baseado em códigos de status do gRPC. Cada resposta da API que resulta em um erro inclui um objeto Status que contém:

• Um código de erro numérico.
• Uma mensagem de erro.
• Detalhes adicionais opcionais do erro.

Códigos de erro canônicos

A API Google Ads usa um conjunto de códigos de erro canônicos definidos pelo gRPC e HTTP. Esses códigos fornecem uma indicação de alto nível do tipo de erro. Sempre verifique esse código numérico primeiro para entender a natureza fundamental do problema.

A tabela a seguir resume os códigos mais comuns que você pode encontrar ao usar a API Google Ads:

Para mais detalhes sobre esses códigos, consulte o Guia de design da API – Códigos de erro.

Entender os detalhes do erro

Além do código de nível superior, a API Google Ads fornece informações de erro mais específicas no campo details do objeto Status. Esse campo geralmente contém um GoogleAdsFailure proto, que inclui uma lista de objetos individuais GoogleAdsError.

Cada GoogleAdsFailure objeto contém:

• errors: uma lista de objetos GoogleAdsError, cada um detalhando um erro específico que ocorreu.
• request_id: um ID exclusivo da solicitação, útil para depuração e suporte.

Cada GoogleAdsError objeto fornece:

• errorCode: um código de erro mais granular e específico da API Google Ads, como AuthenticationError.NOT_ADS_USER.
• message: uma descrição legível do erro específico.
• trigger: o valor que causou o erro, se aplicável.
• location: descreve onde o erro ocorreu na solicitação, incluindo caminhos de campo.
• details: mais detalhes do erro, como motivos de erro não publicados.

Exemplo de detalhes do erro

Quando você recebe um erro, a biblioteca de cliente permite acessar esses detalhes. Por exemplo, um INVALID_ARGUMENT (código 3) pode ter detalhes de GoogleAdsFailure como este:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v24.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations" },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ]
    }
  ]
}

Neste exemplo, apesar do INVALID_ARGUMENT de nível superior, os GoogleAdsFailure detalhes informam que os name e description campos causaram o problema e por quê (REQUIRED e TOO_SHORT, respectivamente).

Localizar detalhes do erro

A maneira como você acessa os detalhes do erro depende se você está usando chamadas de API padrão, falha parcial ou streaming.

Chamadas de API padrão e de streaming

Quando uma chamada de API falha sem usar falha parcial, incluindo streaming chamadas, o GoogleAdsFailure objeto é retornado como parte dos metadados finais nos cabeçalhos de resposta do gRPC. Se você estiver usando REST para chamadas padrão, GoogleAdsFailure será retornado na resposta HTTP. As bibliotecas de cliente geralmente exibem isso como uma exceção com um GoogleAdsFailure atributo.

Falha parcial

Se você estiver usando falha parcial, os erros de operações com falha serão retornados no campo partial_failure_error da resposta, não nos cabeçalhos de resposta. Nesse caso, o GoogleAdsFailure é incorporado a um objeto google.rpc.Status na resposta.

jobs em lote

Para o processamento em lote, os erros de operações individuais podem ser encontrados recuperando os resultados do job em lote após a conclusão do job. Cada resultado da operação vai incluir um campo status que contém detalhes do erro se a operação falhar.

ID da solicitação

O request-id é uma string exclusiva que identifica sua solicitação de API e é essencial para a solução de problemas.

É possível encontrar o request-id em vários lugares:

• GoogleAdsFailure: se uma chamada de API falhar e GoogleAdsFailure for retornado, ele vai conter um request_id.
• Metadados finais: para solicitações bem-sucedidas e com falha, request-id está disponível nos metadados finais da resposta do gRPC.
• Cabeçalhos de resposta: para solicitações bem-sucedidas e com falha, request-id está também disponível nos cabeçalhos de resposta do gRPC e resposta HTTP, com exceção das solicitações de streaming bem-sucedidas.
• SearchGoogleAdsStreamResponse: para solicitações de streaming, cada SearchGoogleAdsStreamResponse mensagem contém um campo request_id.

Ao registrar erros ou entrar em contato com o suporte, inclua o request-id para ajudar no diagnóstico de problemas.

Práticas recomendadas para tratamento de erros

Para criar aplicativos resilientes, implemente as seguintes práticas recomendadas:

1. Inspecionar detalhes do erro: sempre analise o details campo do Status objeto, procurando especificamente por GoogleAdsFailure. O granular errorCode, message, e location dentro de GoogleAdsError fornecem as informações mais acionáveis para depuração e feedback do usuário.

2. Diferenciar erros do cliente e do servidor:

   • Erros do cliente: códigos como INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Eles exigem mudanças na solicitação ou no estado/credenciais do aplicativo. Não tente novamente a solicitação sem resolver o problema.
   • Erros do servidor: códigos como UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Eles sugerem um problema temporário com o serviço da API.

3. Implementar uma estratégia de repetição:

   • Quando tentar novamente: tente apenas para erros de servidor temporários, como UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN e ABORTED.
   • Espera exponencial: use um algoritmo de espera exponencial para aguardar períodos cada vez maiores entre as novas tentativas. Isso ajuda a evitar a sobrecarga de um serviço já estressado. Por exemplo, aguarde 1 segundo, depois 2 segundos, depois 4 segundos, continuando até um número máximo de novas tentativas ou tempo total de espera.
   • Jitter: adicione uma pequena quantidade aleatória de "jitter" aos atrasos de espera para evitar o problema de "excesso de acionamentos", em que muitos clientes tentam novamente simultaneamente.

4. Registre completamente: registre a resposta de erro completa, incluindo todos os detalhes, especialmente o ID da solicitação. Essas informações são essenciais para depuração e para informar problemas ao suporte do Google, se necessário.

5. Forneça feedback do usuário: com base nos códigos e mensagens específicos GoogleAdsError, forneça feedback claro e útil aos usuários do aplicativo. Por exemplo, em vez de apenas "Ocorreu um erro", você pode dizer "O nome da campanha é obrigatório" ou "O ID do grupo de anúncios fornecido não foi encontrado".

Ao seguir estas diretrizes, você pode diagnosticar e tratar com eficiência os erros retornados pela API Google Ads, resultando em aplicativos mais estáveis e fáceis de usar.