Processar respostas de erro

Este guia explica como processar erros retornados pela API Merchant. Entender a estrutura e a estabilidade da resposta de erro é crucial para criar integrações robustas que podem se recuperar automaticamente de falhas ou fornecer feedback significativo aos usuários.

Visão geral

Quando uma solicitação da API Merchant falha, a API retorna um código de status HTTP padrão (4xx ou 5xx) e um corpo de resposta JSON com detalhes sobre o erro. A API Merchant segue o padrão AIP-193 (link em inglês) para detalhes de erros, fornecendo informações legíveis por máquina que permitem que seu aplicativo processe cenários de erros específicos de forma programática.

Estrutura da resposta de erro

A resposta de erro é um objeto JSON que contém campos padrão, como code, message e status. É importante lembrar que ele também inclui uma matriz details. Para processar erros de forma programática, procure um objeto em details em que o @type seja type.googleapis.com/google.rpc.ErrorInfo.

Esse objeto ErrorInfo fornece dados estruturados e estáveis sobre o erro:

  • domain: o agrupamento lógico do erro, geralmente merchantapi.googleapis.com.
  • metadata: um mapa de valores dinâmicos relacionados ao erro. Isso inclui o seguinte:
    • REASON: um identificador específico e estável para o erro exato (por exemplo, INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Esse campo está sempre presente. Use esse campo para tratamento de erros refinado na lógica do aplicativo.
    • HELP_CENTER_LINK: fornece mais contexto e instruções para corrigir o problema. Esse campo não está presente em todos os erros, mas planejamos expandir a cobertura com o tempo para os erros em que mais contexto pode ser necessário.
    • Outros campos dinâmicos: outras chaves que fornecem contexto, como o nome do campo inválido (FIELD_LOCATION) ou o valor que causou o erro (FIELD_VALUE).

Exemplos de respostas de erro

O JSON a seguir demonstra a estrutura de um erro da API Merchant em que um nome de recurso estava malformado.

{
  "error": {
    "code": 400,
    "message": "[name] The part `account` of the resource name in field `name` must be a number, but has value: `abcd`.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "VARIABLE_NAME": "account",
          "FIELD_LOCATION": "name",
          "FIELD_VALUE": "abcd",
          "REASON": "INVALID_NAME_PART_NOT_NUMBER"
        }
      }
    ]
  }
}

Confira um exemplo de erro de autenticação:

{
  "error": {
    "code": 401,
    "message": "The caller does not have access to the accounts: [1234567]",
    "status": "UNAUTHENTICATED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "unauthorized",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_IDS": "[1234567]",
          "REASON": "PERMISSION_DENIED_ACCOUNTS"
        }
      }
    ]
  }
}

Estabilidade dos campos de erro

Ao escrever uma lógica de tratamento de erros, é importante saber em quais campos é seguro confiar e quais podem mudar.

  • Campos estáveis:

  • details.metadata.REASON: o identificador de erro específico. Você deve confiar nesse campo para a lógica de fluxo de controle do seu aplicativo.

    • Chaves details.metadata: as chaves no mapa de metadados (por exemplo, FIELD_LOCATION, ACCOUNT_IDS) são estáveis.
    • code: o código de status HTTP de alto nível (por exemplo, 400, 401, 503) é estável.

  • Campos instáveis:

    • message: a mensagem de erro legível por humanos não é estável. Ele é destinado apenas à depuração de desenvolvedores. Não escreva código que analise ou dependa do conteúdo de texto do campo message, porque ele pode mudar sem aviso prévio para melhorar a clareza ou adicionar contexto.
    • Valores details.metadata: embora as chaves sejam estáveis, os valores das chaves informativas podem mudar. Por exemplo, se uma chave HELP_CENTER_LINK for fornecida, o URL específico a que ela aponta poderá ser atualizado para uma página de documentação mais recente sem notificação prévia. No entanto, como mencionado anteriormente, o valor de details.metadata.REASON é estável.

Práticas recomendadas

Siga estas práticas recomendadas para garantir que sua integração processe erros de maneira adequada.

Usar details.metadata.REASON para lógica

Sempre use o REASON específico dentro do mapa metadata para determinar a causa de um erro. Não confie apenas no código de status HTTP, já que vários erros podem compartilhar o mesmo código.

Não analisar a mensagem de erro

Como observado na seção de estabilidade, o campo message é para consumo humano. Se você precisar de informações dinâmicas (como qual campo era inválido), extraia-as do mapa metadata usando chaves estáveis, como FIELD_LOCATION e VARIABLE_NAME.

Implementar espera exponencial

Para erros que indicam indisponibilidade temporária ou limitação de taxa, implemente uma estratégia de espera exponencial. Isso significa esperar um curto período antes de tentar de novo e aumentar o tempo de espera a cada falha subsequente.

  • quota/request_rate_too_high: esse erro indica que você excedeu a cota de minutos para um grupo específico. Diminua a taxa de solicitação.
  • internal_error: geralmente são temporários. Tente de novo com uma espera exponencial.

Como entrar em contato com o suporte da API Merchant

Se você precisar entrar em contato com o suporte da API Merchant sobre um erro específico, informe o seguinte na sua solicitação:

  1. A resposta de erro exata recebida
  2. O nome do método da API
  3. O payload da solicitação
  4. Carimbos de data/hora ou o período em que o método foi chamado e os erros foram recebidos
Anterior
Track usage metrics
Avançar
Error messages