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 de API é fundamental para criar aplicativos robustos que podem 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 das APIs do Google, que se baseia 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.
  • Opcional, outros detalhes 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 pelo 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 da enumeração 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 ou nos detalhes do erro. Tratar como um erro de servidor. Geralmente pode ser repetida com 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 malformado 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 de novo 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 de novo com espera exponencial.
5 404 NOT_FOUND Algumas entidades solicitadas, como campanhas ou grupos de anúncios, não foram encontradas. Erro do cliente: verifique a existência e o ID dos recursos que você está tentando acessar. Não tente de novo sem corrigir.
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 os papéis do usuário na conta do Google Ads. Não tente de novo 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 requer espera. Implemente a espera exponencial e reduza a taxa de solicitações. Consulte Limites e cotas da API.
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á em branco. Erro do cliente: a solicitação é válida, mas o estado está incorreto. Analise os detalhes do erro para entender a falha de pré-condição. Não tente de novo 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 de novo 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 repita.
13 500 INTERNAL Ocorreu um erro interno. É um intervalo geral para problemas do lado do servidor. Erro do servidor: geralmente pode ser repetido com espera exponencial. Se o problema persistir, informe o problema.
14 503 UNAVAILABLE O serviço não está disponível no momento. Provavelmente é uma condição temporária. Erro do servidor: é altamente recomendável tentar de novo com espera exponencial.
15 500 DATA_LOSS Perda ou corrupção irrecuperável de dados. Erro do servidor: raro. Indica um problema grave. Não repita. Se o problema 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 de novo sem corrigir a autenticação.

Para mais detalhes sobre esses códigos, consulte o Guia de design de 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 mais específicas sobre erros 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 depuração e suporte.

Cada objeto GoogleAdsError fornece:

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 GoogleAdsFailure como este:

{
  "code": 3,
  "message": "The request was invalid.",
  "details": [
    {
      "@type": "type.googleapis.com/google.ads.googleads.v17.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 detalhes de GoogleAdsFailure informam que os campos name e description causaram o problema e por quê (REQUIRED e TOO_SHORT, respectivamente).

Localizar 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 gRPC. Se você estiver usando REST para chamadas padrão, GoogleAdsFailure será retornado na resposta HTTP. As bibliotecas de cliente geralmente apresentam isso como uma exceção com um atributo GoogleAdsFailure.

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 está incorporado em 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 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 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 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. Os errorCode, message e location granulares em GoogleAdsError fornecem as informações mais úteis para depuração e feedback do usuário.

  2. Diferencie erros de cliente e de servidor:

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

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

    • Quando tentar de novo: tente apenas em 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 sobrecarregar um serviço já estressado. Por exemplo, aguarde 1 segundo, depois 2 segundos, depois 4 segundos e continue 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 "excesso de acionamentos", em que muitos clientes tentam novamente ao mesmo tempo.

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

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

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