Tratamento de Erros

Estratégia recomendada

Trate os erros em três níveis:

• falhas de autenticação;
• erros de validação de dados;
• erros de negócio da plataforma.

Como pensar as falhas de autenticação

Falhas de autenticação normalmente indicam divergência entre a sessão ativa do usuário, a credencial de integração utilizada e a configuração liberada para a conta.

Como pensar erros de validação

Erros de validação surgem quando os dados enviados não respeitam os formatos, as regras de preenchimento ou as relações esperadas entre customer, cobrança e pagador.

Como pensar erros de negócio

Erros de negócio costumam representar situações em que o contrato técnico da API está correto, mas a operação não pode prosseguir por contexto funcional, restrição de acesso, inconsistência de titularidade ou indisponibilidade temporária do fluxo.

Boas práticas

• registre o contexto da chamada, o tipo do erro e o momento em que a falha ocorreu;
• não grave credenciais nos logs;
• associe o erro aos identificadores operacionais da sua transação quando existirem;
• implemente mensagens de erro claras no seu sistema;
• aplique retentativa apenas em cenários transitórios.

Onde ver os detalhes técnicos

Os códigos HTTP, exemplos de erro, estruturas de resposta e cenários por endpoint ficam concentrados na área API Reference.