Skip to main content
Quando uma requisição não dá certo, a API responde com um código HTTP e um corpo JSON que explica o motivo. Esta página mostra como ler esse corpo, o que cada código significa e qual reação o seu sistema deve ter. A lista completa de mensagens por rota está no Catálogo de códigos de erro.
Para o negócio: um bom tratamento de erros evita dois problemas para a operação: cobrar o cliente duas vezes (por repetir uma requisição que já tinha funcionado) e perder uma venda (por não mostrar ao cliente uma alternativa quando o cartão é recusado). Os dois casos estão cobertos abaixo.

Formato da resposta de erro

A API usa três formatos de corpo de erro. O formato depende da rota e do tipo de erro, então o seu código precisa aceitar os três. 1. Formato padrão, com statusCode, message e error. É o da maior parte das rotas:
Nos erros de validação do corpo (campo ausente, tipo errado, valor fora do limite), o código é 400 e message vem como lista de textos, um por problema:
O 401 vem só com statusCode e message: { "statusCode": 401, "message": "Unauthorized" }. 2. Formato com código de negócio, com code e message, sem statusCode. Aparece nos erros de negócio do Apple Pay e na validação de cartão da criação de assinatura:
Nessas mesmas rotas, os erros de validação de campo e de permissão continuam no formato padrão. 3. Formato do envio de documentos com token, com error, message e details, sem statusCode. Aparece nos erros de arquivo de POST /v1/document-uploads:
Nessa rota, os erros do token (401 e 403) voltam ao formato padrão.
Para o desenvolvedor: decida o fluxo pelo código HTTP e, quando existir, pelo campo code (formato 2) ou error (formato 3). Use o message só para log e suporte. As mensagens misturam português e inglês (Cobrança não encontrada, Insufficient balance. Required: X, Available: Y) e podem mudar. Não faça comparação exata de texto para decidir regra de negócio.
Node.js

Erro de permissão por perfil

A chave age com as permissões do usuário que a gerou. Quando o perfil desse usuário não tem permissão para a rota, a resposta é 403:
Isso acontece, por exemplo, com chave gerada por usuário Desenvolvedor ao criar cobrança, em saldo e em saques, e com chave de Desenvolvedor ou Financeiro nas rotas de planos e assinaturas. Gere a chave com um usuário Owner ou Manager. Veja Permissões da chave.

Resultados que não são erro HTTP

Códigos HTTP usados pela API

Sucesso

201 na criação de uma cobrança não significa pagamento aprovado. Leia o campo status: no cartão, ele pode vir refused ou failed. No Pix, vem pending até o cliente pagar.

Erros do cliente (4xx)

O desenho abaixo resume a primeira coisa a conferir em cada código 4xx. Os exemplos de mensagem estão na tabela.

Erros do servidor (5xx)

Quando repetir uma requisição

O desenho abaixo mostra quando repetir uma requisição, conforme o código recebido e o tipo de operação.
A API não tem Idempotency-Key: antes de repetir um POST /v1/charges depois de um 500 ou timeout, siga o procedimento em Idempotência.

Como tratar no código

Node.js

Recusa de cartão: trate como resultado de negócio

Node.js

Boas práticas

  • Registre o corpo completo do erro com rota, método, código HTTP e horário. Sem dados de cartão e sem a chave.
  • Não repita erros 4xx sem corrigir a causa. Eles indicam que nada foi feito.
  • Repita 5xx e timeouts só com verificação prévia nas operações que criam ou alteram algo.
  • Use espera crescente entre tentativas (por exemplo, 1, 2 e 4 segundos) e um limite de tentativas.
  • Defina um timeout nas suas chamadas para não deixar o checkout preso.
  • Separe mensagem técnica de mensagem ao cliente. O message da API vai para o log. O cliente vê um texto amigável com a próxima ação possível.
  • Monitore a taxa de erros por rota. Um aumento de 401 pode indicar chave trocada; de 403, permissão do usuário que gerou a chave; de 422, mudança na configuração da conta ou no payload enviado.

Erros comuns

Perguntas frequentes

Não. A cobrança é criada com 201, e o status vem refused ou failed, com o motivo em reason. Trate como resultado de negócio e ofereça outra forma de pagamento.
Não é recomendado. As mensagens são técnicas e misturam português e inglês. Mostre um texto próprio e guarde o message no log. A exceção é o CARD_VALIDATION_FAILED, cujo message foi feito para exibição.
Pode existir. Antes de repetir, siga a verificação descrita em Paginação, ordenação e idempotência.
No Catálogo de códigos de erro, agrupado por rota, e na página de referência de cada rota.

Como testar

  • Envie uma requisição sem o cabeçalho Authorization e confira o tratamento do 401.
  • Envie um item physical sem shippingAddress e confira o tratamento do 400 (cenário CHG-10).
  • Envie um corpo com um campo obrigatório faltando e confira se o seu código lê message como lista.
  • Consulte um id inexistente em GET /v1/charges/{id} e confira se o seu código trata o 200 com corpo vazio.
  • Crie uma cobrança com o cartão de teste 4444333322221112 e confira o tratamento de refused (cenário CHG-03 do roteiro de homologação).
  • Em split, comprove que a sua integração trata a rejeição de percentual inválido e de merchantId fora do grupo (cenários SPL-03 e SPL-04).

Veja também

Catálogo de códigos de erro

Todas as mensagens literais, por rota.

Paginação, ordenação e idempotência

Como repetir sem duplicar.

Credenciais e ambientes

Chaves, permissões e autenticação.

Status de cobrança

O que fazer em cada status.