Códigos de erro

Esta página descreve os códigos de erro canônicos que você precisa retornar nas respostas da API ao fazer a integração com o Google usando o Protocolo de Comércio Universal (UCP). Códigos de erro consistentes garantem uma comunicação clara e ajudam o Google a lidar com diferentes cenários de maneira adequada.

Quando um erro comercial ocorre, a API precisa retornar uma mensagem de resposta que inclua o code apropriado da tabela. Para alguns códigos de erro, uma estrutura JSON específica é recomendada para a matriz messages na resposta. Esses exemplos são fornecidos na seção Exemplos de código de erro abaixo da tabela. Nesses exemplos, use o campo path para fornecer informações mais específicas sobre a localização do erro no objeto de solicitação ou resposta.

Tratamento de erros

A forma de informar erros depende do tipo:

• Erros de protocolo/servidor:

  • Use códigos de status HTTP padrão (por exemplo, 4xx para erros do cliente, 5xx para erros do servidor) em problemas como solicitações malformadas, falhas de autenticação ou indisponibilidade do servidor.
  • Consulte a especificação da UCP para mais detalhes.

• Erros/avisos de lógica de negócios:

  • Retorne um status HTTP 200 OK. Isso inclui recusas de pagamento e rejeições por fraude, mesmo que o gateway de pagamento downstream retorne um erro 4xx ou 5xx.
  • Descreva o problema na matriz messages no corpo da resposta JSON.
  • Cada objeto na matriz messages precisa incluir:
    • type: "error" ou "warning".
    • code: um código padronizado deste guia. Não use códigos genéricos ou não reconhecidos, como "invalid".
    • content: uma descrição legível.
    • severity: obrigatório quando type é "error". Esse campo indica explicitamente se o erro é fatal (unrecoverable) ou permite solicitar que o comprador corrija o problema (recoverable), em vez de depender do próprio código de erro.

Tipos de mensagens: erro x aviso

O campo type na matriz de mensagens indica a gravidade do problema. O UCP define dois tipos principais:

• error: indica que não foi possível concluir a operação solicitada. A plataforma ou o usuário provavelmente precisará tomar medidas e tentar de novo. Consulte message-error specification.
  • A natureza terminal de um erro é determinada pelo campo severity (unrecoverable ou recoverable), não pelo erro code.
• warning: indica que a operação não foi bloqueada, mas há algo importante que precisa ser comunicado ao usuário. Isso não interrompe o processo, mas fornece um contexto importante. Consulte a especificação message-warning.

Referência do código de erro

Exemplos de códigos de erro

Esta seção fornece exemplos de JSON para a matriz messages de códigos de erro específicos.

out_of_stock

Finalização da compra de um único item:

{
  "type": "error",
  "severity": "unrecoverable",
  "code": "out_of_stock",
  "content": "Unfortunately, the item 'Example Product 1' is out of stock."
}

Finalização de compra de vários itens:

Use o campo path para indicar o índice do item específico que está fora de estoque.

{
  "type": "error",
  "severity": "recoverable",
  "code": "out_of_stock",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' is out of stock. Remove it from your cart to continue."
}

quantity_invalid_limit_exceeded

{
  "type": "error",
  "severity": "recoverable",
  "code": "quantity_invalid_limit_exceeded",
  "path": "$.checkout.line_items[0].quantity",
  "content": "The requested quantity for 'Example Product 2' exceeds the maximum allowed limit of 5."
}

totals_changed

{
  "type": "warning",
  "code": "totals_changed",
  "path": "$.totals[2]",
  "content": "Shipping cost has changed."
}

missing_buyer_info

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_buyer_info",
  "path": "$.buyer.first_name",
  "content": "Missing buyer first name."
}

address_undeliverable

Restrição no nível do pedido (por exemplo, CEP indisponível):

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "content": "Delivery is not supported for the provided zipcode."
}

Restrição no nível do item:

Use o campo path para indicar um item específico que não pode ser entregue no destino escolhido (por exemplo, proibições específicas de um estado).

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_undeliverable",
  "path": "$.checkout.line_items[1]",
  "content": "The item 'Example Product 2' cannot be delivered to the selected address."
}

address_unverifiable

Endereço de faturamento:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.payment.instruments[0].billing_address",
  "content": "Invalid billing address. Update the address before trying again."
}

Endereço de fulfillment:

{
  "type": "error",
  "severity": "recoverable",
  "code": "address_unverifiable",
  "path": "$.fulfillment.methods[0].destinations[0]",
  "content": "The fulfillment address couldn't be verified. Update the address and try again."
}

missing_billing_info

Use o campo path para especificar campos ausentes no endereço de faturamento.

{
  "type": "error",
  "severity": "recoverable",
  "code": "missing_billing_info",
  "path": "$.payment.instruments[0].billing_address.street_address",
  "content": "Missing billing street address."
}

identity_required

Na API REST, esse erro precisa ser retornado com o código de status HTTP 401.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "identity_required",
  "content": "User identity is required to access order history."
}

insufficient_scope

Na API REST, esse erro precisa ser retornado com o código de status HTTP 403.

{
  "type": "error",
  "severity": "requires_buyer_review",
  "code": "insufficient_scope",
  "content": "This operation requires scopes: dev.ucp.shopping.order:read, dev.ucp.shopping.order:manage"
}

Erros de pagamento

payment_declined

{
  "type": "error",
  "severity": "recoverable",
  "code": "payment_declined",
  "path": "$.payment.instruments[0]",
  "content": "Payment was declined by the issuer. Try a different payment method or contact your bank."
}

rejected_for_fraud

{
  "type": "error",
  "severity": "recoverable",
  "code": "rejected_for_fraud",
  "path": "$.payment.instruments[0]",
  "content": "The order was rejected due to suspected fraud. Try a different payment method."
}