> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.gomoney.me/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.gomoney.me/_mcp/server.

# 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](./api-reference-overview).