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, comstatusCode, message e error. É o da maior parte das rotas:
400 e message vem como lista de textos, um por problema:
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:
401 e 403) voltam ao formato padrão.
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:
Resultados que não são erro HTTP
Códigos HTTP usados pela API
Sucesso
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.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
4xxsem corrigir a causa. Eles indicam que nada foi feito. - Repita
5xxe 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
messageda 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
401pode indicar chave trocada; de403, permissão do usuário que gerou a chave; de422, mudança na configuração da conta ou no payload enviado.
Erros comuns
Perguntas frequentes
A recusa do cartão aparece como erro HTTP?
A recusa do cartão aparece como erro HTTP?
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.Posso mostrar o message da API para o cliente final?
Posso mostrar o message da API para o cliente final?
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.Recebi 500 ao criar uma cobrança. A cobrança existe?
Recebi 500 ao criar uma cobrança. A cobrança existe?
Pode existir. Antes de repetir, siga a verificação descrita em Paginação, ordenação e idempotência.
Onde vejo todas as mensagens possíveis de uma rota?
Onde vejo todas as mensagens possíveis de uma rota?
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
Authorizatione confira o tratamento do401. - Envie um item
physicalsemshippingAddresse confira o tratamento do400(cenário CHG-10). - Envie um corpo com um campo obrigatório faltando e confira se o seu código lê
messagecomo lista. - Consulte um
idinexistente emGET /v1/charges/{id}e confira se o seu código trata o200com corpo vazio. - Crie uma cobrança com o cartão de teste
4444333322221112e confira o tratamento derefused(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
merchantIdfora 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.

