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 possam se recuperar automaticamente de falhas ou fornecer feedback significativo aos usuários.

Visão geral

Quando uma solicitação de API Merchant falha, a API retorna um código de status HTTP padrão (4xx ou 5xx) e um corpo de resposta JSON contendo 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. É fundamental que ela também inclua uma matriz details. Para processar erros de maneira programática, procure um objeto em details em que @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, normalmente merchantapi.googleapis.com.
  • metadata: um mapa de valores dinâmicos relacionados ao erro. Isso inclui:
    • REASON: um identificador específico e estável para o erro exato (por exemplo, INVALID_NAME_PART_NOT_NUMBER, PERMISSION_DENIED_ACCOUNTS). Este campo está sempre presente. Use esse campo para tratamento de erros refinado na lógica do aplicativo.
    • HELP_CENTER_LINK: fornece contexto e instruções adicionais para corrigir o problema. Esse campo não está presente para todos os erros, mas planejamos expandir a cobertura ao longo do 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 erros

O JSON a seguir demonstra a estrutura de um erro da API Merchant em que um nome de recurso foi 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 a 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 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 não é estável. Ela é destinada apenas à depuração do desenvolvedor. Não escreva códigos que analisem ou dependam do conteúdo de texto do campo message field, 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 para o qual 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 corretamente.

Usar details.metadata.REASON para lógica

Sempre use o REASON específico no 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 de status.

Não analise 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, VARIABLE_NAME.

Implementar a 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 a cota de minutos para um grupo de cotas específico. Diminua a taxa de solicitação.
  • internal_error: geralmente são temporários. Tentar novamente com a 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, forneça as seguintes informações na 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