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 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 vão aparecer 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:

• error_code: um código de erro específico que informa o tipo de erro, como AuthenticationError.NOT_ADS_USER.
• message: uma descrição legível do motivo do erro.
• trigger: o valor que causou o erro, como "1234".
• location: detalhes sobre qual parte da solicitação causou o erro, como um nome de campo específico.

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

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

Como processar erros

Se você encontrar um erro, siga estas etapas:

1. Examine a lista errors: analise cada GoogleAdsError no objeto GoogleAdsFailure. Os error_code e message vão informar o que deu errado.
2. Verifique o location: o campo location pode ajudar você a identificar em qual parte da solicitação o problema ocorreu.
3. 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.
4. 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.
5. Registre o request_id: se você não conseguir resolver um erro e precisar entrar em contato com o suporte pelo fórum, inclua o request_id. Esse ID ajuda os engenheiros do Google a 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.