Entender os erros da API

Neste guia, explicamos como a API Google Ads lida com erros e os comunica. Entender a estrutura e o significado dos erros de API é crucial para criar aplicativos robustos que possam lidar com problemas, desde entradas inválidas até indisponibilidade temporária de serviço.

A API Google Ads segue o modelo de erro padrão da API do Google, que é baseado nos 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 do 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 por 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:

Código gRPC Código HTTP Nome do tipo enumerado Descrição Orientação
0 200 OK Nenhum erro. Indica sucesso. N/A
1 499 CANCELLED A operação foi cancelada, geralmente pelo cliente. Normalmente significa que o cliente parou de esperar. Verifique os tempos limite do lado do cliente.
2 500 UNKNOWN Ocorreu um erro desconhecido. Mais detalhes podem estar na mensagem de erro ou nos detalhes. Trate como um erro de servidor. Geralmente, é possível tentar novamente com uma espera.
3 400 INVALID_ARGUMENT O cliente especificou um argumento inválido. Isso indica um problema que impede a API de processar a solicitação, como um nome de recurso incorreto ou um valor inválido. Erro do cliente: revise os parâmetros da solicitação e verifique se eles atendem aos requisitos da API. Os detalhes do erro geralmente fornecem informações sobre qual argumento era inválido e como. Use esses detalhes para corrigir a solicitação. Não tente novamente sem corrigir a solicitação.
4 504 DEADLINE_EXCEEDED O prazo expirou antes do término da operação. Erro de servidor: geralmente temporário. Tente novamente com uma espera exponencial.
5 404 NOT_FOUND Alguma entidade solicitada, como uma campanha ou um grupo de anúncios, não foi encontrada. Erro do cliente: verifique a existência e o ID dos recursos que você está tentando acessar. Não tente novamente sem fazer as correções.
6 409 ALREADY_EXISTS A entidade que o cliente tentou criar já existe. Erro do cliente: evite criar recursos duplicados. Verifique se o recurso existe antes de tentar criá-lo.
7 403 PERMISSION_DENIED O autor da chamada não tem permissão para executar a operação especificada. Erro do cliente: verifique a autenticação, a autorização e as funções de usuário da conta do Google Ads. Não tente novamente sem resolver as permissões.
8 429 RESOURCE_EXHAUSTED Um recurso foi esgotado (por exemplo, você excedeu sua cota) ou um sistema está sobrecarregado. Erro de cliente/servidor: geralmente, é preciso esperar. Implemente a espera exponencial e reduza a taxa de solicitação. Consulte limites da API e cotas.
9 400 FAILED_PRECONDITION A operação foi rejeitada porque o estado do sistema não é o necessário para a execução dela. Por exemplo, um campo obrigatório está ausente. Erro do cliente: a solicitação é válida, mas o estado está incorreto. Analise os detalhes do erro para entender a falha de condição prévia. Não tente novamente sem corrigir o estado.
10 409 ABORTED A operação foi cancelada, geralmente devido a um problema de simultaneidade, como um conflito de transação. Erro de servidor: geralmente é seguro tentar novamente com uma espera curta.
11 400 OUT_OF_RANGE Houve uma tentativa da operação depois do intervalo válido. Erro do cliente: corrija o intervalo ou o índice.
12 501 UNIMPLEMENTED A operação não foi implementada ou não é compatível com a API. Erro do cliente: verifique a versão da API e os recursos disponíveis. Não tente de novo.
13 500 INTERNAL Ocorreu um erro interno. Este é um erro geral para problemas do lado do servidor. Erro de servidor: geralmente, é possível tentar novamente com espera exponencial. Se o erro persistir, informe o problema.
14 503 UNAVAILABLE O serviço está temporariamente indisponível. Muito provavelmente, trata-se de uma condição temporária. Erro de servidor: é altamente recomendável tentar novamente com espera exponencial.
15 500 DATA_LOSS Perda ou corrupção irrecuperável de dados. Erro de servidor: raro. Indica um problema sério. Não tente de novo. Se o erro persistir, informe o problema.
16 401 UNAUTHENTICATED A solicitação não tem credenciais de autenticação válidas. Erro do cliente: verifique seus tokens de autenticação e credenciais. Não tente novamente sem corrigir a autenticação.

Para mais detalhes sobre esses códigos, consulte o Guia de design de API: códigos do 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 proto GoogleAdsFailure, que inclui uma lista de objetos GoogleAdsError individuais.

Cada objeto GoogleAdsFailure contém:

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

Cada objeto GoogleAdsError fornece:

Exemplo de detalhes do erro

Quando você recebe um erro, a biblioteca de cliente permite que você acesse 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.v26.errors.GoogleAdsFailure",
      "errors": [
        {
          "errorCode": {
            "fieldError": "REQUIRED"
          },
          "message": "The required field was not present.",
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "name" }
            ]
          }
        },
        {
          "errorCode": {
            "stringLengthError": "TOO_SHORT"
          },
          "message": "The provided string is too short.",
          "trigger": {
            "stringValue": ""
          },
          "location": {
            "fieldPathElements": [
              { "fieldName": "operations", "index": 0 },
              { "fieldName": "create" },
              { "fieldName": "description" }
            ]
          }
        }
      ],
      "requestId": "AbCdEfGhIjKlMnOpQrStUv"
    }
  ]
}

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

Encontrar detalhes do erro

A forma de acessar 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 chamadas de streaming, o objeto GoogleAdsFailure é 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 mostram isso como uma exceção com um atributo GoogleAdsFailure.

Falha parcial

Se você estiver usando a 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 processamento em lote, os erros de operações individuais podem ser encontrados chamando BatchJobService.ListBatchJobResults após a conclusão do job. Cada resultado de operação vai incluir um campo status com 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.

Você pode 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 também está disponível nos cabeçalhos de resposta gRPC e resposta HTTP, exceto para solicitações de streaming bem-sucedidas.
  • SearchGoogleAdsStreamResponse: para solicitações de streaming, cada mensagem SearchGoogleAdsStreamResponse 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. Inspecione os detalhes do erro: sempre analise o campo details do objeto Status, procurando especificamente por GoogleAdsFailure. As informações granulares error_code, message e location em GoogleAdsError fornecem as informações mais úteis para depuração e feedback do usuário.

  2. Diferencie os erros de cliente dos erros de servidor:

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

  3. Implemente uma estratégia de novas tentativas:

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

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

  5. Forneça feedback ao usuário: com base nos códigos e nas mensagens específicos de 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 essas diretrizes, você pode diagnosticar e lidar com erros retornados pela API Google Ads, o que resulta em aplicativos mais estáveis e fáceis de usar.

Anterior
Tipos de erro
Avançar
Erros comuns