Processar respostas de erro

Este guia explica como lidar com erros retornados pela API Merchant. Entender a estrutura e a estabilidade da resposta de erro é fundamental 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 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 maneira 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 ressaltar que ele também inclui uma matriz details. Para processar erros de forma programática, procure um objeto em details em que o @type é type.googleapis.com/google.rpc.ErrorInfo.

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

  • domain: o agrupamento lógico do erro, normalmente 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. Confie 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) estão estáveis.
    • code: o código de status HTTP de alto nível (por exemplo, 400, 401, 503) está estável.

  • Campos instáveis:

    • message: a mensagem de erro legível 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 aviso prévio. 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

Conforme 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 novamente e aumentar o tempo de espera a cada falha subsequente.

  • quota/request_rate_too_high: esse erro indica que você excedeu sua cota de minuto para um grupo de cotas específico. Reduza a taxa de solicitação.
  • internal_error: geralmente são temporários. Tente de novo com espera exponencial. Observação:se o problema internal_error persistir após várias tentativas com redução exponencial, consulte Como entrar em contato com o suporte da API Merchant.

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, forneça as seguintes informações 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