Tratamento de erros

Ao integrar com as APIs da Lerian, um tratamento robusto de erros é essencial para uma experiência de usuário fluida e um desempenho de aplicação resiliente. Este guia explica como os erros são estruturados, como classificá-los e como responder a diferentes categorias de erro.

Modelo de resposta de erro

Todas as APIs da Lerian retornam um objeto de erro estruturado para cada erro. O formato é consistente em todos os serviços:

{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}

Definições dos campos:

code: Um identificador único e estável para o erro. Use este campo para tratamento programático de erros.
title: Um resumo breve do problema.
message: Orientação detalhada e legível para resolver o erro.

Sempre use o campo code para identificar erros programaticamente. Títulos e mensagens podem evoluir para melhorar a clareza, mas os códigos de erro permanecem estáveis.

Detalhes de erro em nível de campo

Quando um erro se relaciona a campos específicos no payload da requisição, a resposta inclui um objeto fields com detalhes granulares:

{
   "code": "CRM-0003",
   "title": "Missing Fields in Request",
   "message": "Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request.",
   "fields": {
      "document": "document is a required field"
   }
}

{
   "code": "CRM-0047",
   "title": "Bad Request",
   "message": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
   "fields": {
      "legalName": "legalName is a required field.",
      "parentOrganizationId": "parentOrganizationId must be a valid UUID"
   }
}

{
   "code": "CRM-0053",
   "title": "Unexpected Fields in the Request",
   "message": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
   "fields": {
      "extraField": "extraField is not allowed"
   }
}

Estrutura de códigos de erro

Cada código de erro segue um formato padronizado que identifica tanto o serviço quanto o erro específico:

<PREFIX>-<NNNN>

PREFIX (3 letras): Identifica o serviço ou plugin que produziu o erro.
NNNN (4 dígitos): Um número único dentro daquele serviço.

Prefixos de serviço

Prefixo	Serviço
AUT	Access Manager (autenticação)
IDE	Access Manager (identidade)
CRM	CRM
FEE	Fees Engine
PIX	PIX
BTF	Bank Transfer (TED)
TPL	Reporter
TRC	Tracer

O Midaz core usa códigos somente numéricos (ex.: 0002, 0009) sem prefixo. Todos os outros serviços incluem seu prefixo de 3 letras.

Faixas de números

Os códigos de erro são organizados em faixas que indicam a origem do erro:

Faixa	Categoria	Descrição
`0001`–`0099`	Sistema e middleware	Autenticação, autorização, cabeçalhos, rate limiting
`0100`–`0999`	Específico do serviço	Validação, lógica de negócio e erros de domínio dentro do plugin
`1000`–`1999`	Integração externa	Erros originados em provedores externos ou serviços upstream

Essa estrutura permite que você identifique rapidamente se um erro vem da sua requisição (números baixos), da lógica de negócio do serviço (faixa intermediária) ou de uma dependência externa (1000+).

Classificação de erros

Compreender o tipo de erro ajuda a decidir como responder. Os erros da Lerian se classificam em três categorias:

Erros de validação

Erros causados por dados incorretos ou ausentes na requisição. Características:

Status HTTP 400 (Bad Request)
Incluem um objeto fields quando campos específicos são os causadores
Sempre evitáveis validando os dados antes de enviar

Exemplos: Campos obrigatórios ausentes, UUIDs inválidos, valores de enumeração não suportados, campos que excedem o comprimento máximo. O que fazer: Verifique o objeto fields para detalhes específicos. Corrija os dados e tente novamente.

Erros de lógica de negócio

Erros causados por operações que violam regras de domínio ou restrições de estado de recursos. Características:

Status HTTP 404 (Not Found), 409 (Conflict) ou 422 (Unprocessable Entity)
Indicam que a requisição é sintaticamente válida mas não pode ser processada

Exemplos: Recurso não encontrado, conflitos de nome duplicado, transições de estado inválidas (ex.: ativar uma regra já ativa), saldo insuficiente. O que fazer: Verifique se o recurso existe e está no estado esperado. Leia a mensagem de erro para a restrição específica que foi violada.

Erros de sistema

Erros causados por problemas de infraestrutura, timeouts ou falhas inesperadas. Características:

Status HTTP 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable) ou 504 (Gateway Timeout)
Não são causados pelos seus dados — a mesma requisição pode ter sucesso depois

Exemplos: Erro interno do servidor, serviço temporariamente indisponível, gateway timeout. O que fazer: Tente novamente com backoff exponencial (veja orientação abaixo). Se o erro persistir, entre em contato com o suporte.

Códigos de status HTTP

As APIs da Lerian usam um conjunto focado de códigos de status HTTP:

Código	Significado	Categoria
`400`	Bad Request	Erro de validação — corrija a requisição
`401`	Unauthorized	Credenciais de autenticação ausentes ou inválidas
`403`	Forbidden	Credenciais válidas mas permissões insuficientes
`404`	Not Found	O recurso solicitado não existe
`409`	Conflict	A operação conflita com o estado atual do recurso
`422`	Unprocessable Entity	Sintaxe válida mas viola regras de negócio
`429`	Too Many Requests	Limite de taxa excedido — aguarde e tente novamente
`500`	Internal Server Error	Falha inesperada do servidor — tente novamente depois
`502`	Bad Gateway	Serviço upstream retornou uma resposta inválida
`503`	Service Unavailable	Serviço temporariamente indisponível — tente novamente depois
`504`	Gateway Timeout	Requisição expirou — tente novamente depois

Orientação de retentativas

Nem todos os erros devem ser retentados. A tabela a seguir ajuda a decidir:

Tipo de erro	Retentável	Ação recomendada
`400` erros de validação	Não	Corrija o payload da requisição
`401` / `403` erros de auth	Não	Verifique credenciais e permissões
`404` não encontrado	Não	Verifique o ID do recurso
`409` conflitos	Às vezes	Verifique o estado atual, depois tente novamente se o conflito foi resolvido
`422` lógica de negócio	Não	Ajuste a operação para cumprir as regras de negócio
`429` limite de taxa	Sim	Aguarde a janela de retentativa, depois tente novamente
`500` erros internos	Sim	Tente novamente com backoff exponencial
`502` / `503` / `504`	Sim	Tente novamente com backoff exponencial

Estratégia de backoff exponencial

Para erros retentáveis, use backoff exponencial para evitar sobrecarregar o serviço:

Primeira retentativa: Aguarde 1 segundo
Segunda retentativa: Aguarde 2 segundos
Terceira retentativa: Aguarde 4 segundos
Máximo de retentativas: Pare após 3–5 tentativas
Jitter: Adicione um pequeno atraso aleatório (0–500ms) a cada espera para prevenir efeito manada

Nunca tente novamente automaticamente erros 400, 401, 403 ou 422. Estes indicam problemas com sua requisição que devem ser corrigidos antes de tentar novamente.

Resolução de problemas por categoria

Campos ausentes ou inválidos (400)

A maioria dos erros 400 inclui um objeto fields que indica exatamente quais campos precisam de atenção. Causas comuns:

Campo obrigatório omitido do corpo da requisição
Valor do campo não corresponde ao tipo esperado (ex.: string em vez de UUID)
Valor do campo excede o comprimento máximo
Campos extras inesperados no corpo da requisição

Passos de resolução:

Leia o objeto fields na resposta de erro
Compare sua requisição com a referência da API para aquele endpoint
Verifique se os nomes de campo usam lowerCamelCase (não snake_case)
Verifique se as datas usam formato ISO 8601 com sufixo Z
Verifique se os UUIDs são formato v4 válido

Autenticação e autorização (401/403)

Causas comuns:

Cabeçalho Authorization ausente
Token expirado ou revogado
O token não concede acesso ao endpoint solicitado

Passos de resolução:

Confirme que o Access Manager está habilitado no seu ambiente
Verifique se o token está presente no cabeçalho Authorization
Solicite um novo token se o atual expirou
Verifique se o escopo do token inclui as permissões necessárias

Recurso não encontrado (404)

Causas comuns:

ID de recurso incorreto no caminho da URL
Recurso foi deletado (soft-delete)
Recurso pertence a uma organização ou ledger diferente

Passos de resolução:

Verifique o formato do ID (deve ser um UUID válido)
Liste recursos para confirmar que o ID existe
Verifique se está usando os parâmetros de caminho organizationId e ledgerId corretos

Erros de conflito (409)

Causas comuns:

Criar um recurso com um nome que já existe (ex.: nome de ledger duplicado, nome de regra duplicado)
Tentar uma operação que já foi concluída (ex.: transação duplicada)

Passos de resolução:

Leia a mensagem de erro para identificar qual campo causou o conflito
Use um valor diferente (ex.: renomeie) ou recupere o recurso existente
Para operações idempotentes, verifique se o recurso existente corresponde à sua intenção

Limite de taxa (429)

Causas comuns:

Muitas requisições em um período curto

Passos de resolução:

Implemente backoff exponencial com jitter
Reduza a frequência de chamadas à API
Agrupe operações onde possível

Erros de servidor e timeout (500/502/503/504)

Causas comuns:

Interrupção temporária do serviço
Alta carga na plataforma
Dependência upstream indisponível

Passos de resolução:

Tente novamente com backoff exponencial (1s, 2s, 4s)
Se o erro persistir após 3–5 retentativas, entre em contato com o suporte
Registre a resposta de erro completa (incluindo code) para escalamento ao suporte

Listas de erros por serviço

Cada serviço da Lerian publica uma lista completa de seus códigos de erro. Use estas referências para buscar códigos de erro específicos:

Serviço	Lista de erros
Midaz	Lista de erros do Midaz
Access Manager	Lista de erros do Access Manager
CRM	Lista de erros do CRM
Fees Engine	Lista de erros do Fees Engine
Bank Transfer (TED)	Lista de erros do TED
Reporter	Lista de erros do Reporter
Tracer	Lista de erros do Tracer

Boas práticas

1. Use códigos de erro para tratamento programático

Códigos de erro são identificadores estáveis projetados para automação. Mapeie códigos específicos para caminhos de resolução na sua integração:

if error.code == "TRC-0100":
    # Rule not found — verify rule ID
elif error.code.startswith("TRC-01"):
    # Rule-related error — check rule configuration
elif error.code.startswith("TRC-0"):
    # Tracer validation error — check request format

2. Registre erros com contexto

Inclua a resposta de erro completa, a requisição que a disparou e o timestamp. Isso torna o escalamento ao suporte mais rápido e o debugging mais eficaz.

3. Trate erros em nível de campo

Quando a resposta inclui um objeto fields, exiba essas mensagens específicas para seus usuários em vez de mostrar um erro genérico.

4. Implemente circuit breakers para integrações

Se você receber erros 500, 502 ou 503 repetidos, use um padrão de circuit breaker para parar temporariamente de chamar o serviço com falha e prevenir falhas em cascata.

5. Mantenha-se atualizado

Revise as páginas de lista de erros periodicamente. Novos códigos de erro podem ser adicionados conforme os serviços evoluem.

Visão geral

Fundamentos de integração

Estabilidade e qualidade

Tratamento de erros

Modelo de resposta de erro

Detalhes de erro em nível de campo

Estrutura de códigos de erro

Prefixos de serviço

Faixas de números

Classificação de erros

Erros de validação

Erros de lógica de negócio

Erros de sistema

Códigos de status HTTP

Orientação de retentativas

Estratégia de backoff exponencial

Resolução de problemas por categoria

Campos ausentes ou inválidos (400)

Autenticação e autorização (401/403)

Recurso não encontrado (404)

Erros de conflito (409)

Limite de taxa (429)

Erros de servidor e timeout (500/502/503/504)

Listas de erros por serviço

Boas práticas

1. Use códigos de erro para tratamento programático

2. Registre erros com contexto

3. Trate erros em nível de campo

4. Implemente circuit breakers para integrações

5. Mantenha-se atualizado

​Modelo de resposta de erro

​Detalhes de erro em nível de campo

​Estrutura de códigos de erro

​Prefixos de serviço

​Faixas de números

​Classificação de erros

​Erros de validação

​Erros de lógica de negócio

​Erros de sistema

​Códigos de status HTTP

​Orientação de retentativas

​Estratégia de backoff exponencial

​Resolução de problemas por categoria

​Campos ausentes ou inválidos (400)

​Autenticação e autorização (401/403)

​Recurso não encontrado (404)

​Erros de conflito (409)

​Limite de taxa (429)

​Erros de servidor e timeout (500/502/503/504)

​Listas de erros por serviço

​Boas práticas

​1. Use códigos de erro para tratamento programático

​2. Registre erros com contexto

​3. Trate erros em nível de campo

​4. Implemente circuit breakers para integrações

​5. Mantenha-se atualizado

Modelo de resposta de erro

Detalhes de erro em nível de campo

Estrutura de códigos de erro

Prefixos de serviço

Faixas de números

Classificação de erros

Erros de validação

Erros de lógica de negócio

Erros de sistema

Códigos de status HTTP

Orientação de retentativas

Estratégia de backoff exponencial

Resolução de problemas por categoria

Campos ausentes ou inválidos (400)

Autenticação e autorização (401/403)

Recurso não encontrado (404)

Erros de conflito (409)

Limite de taxa (429)

Erros de servidor e timeout (500/502/503/504)

Listas de erros por serviço

Boas práticas

1. Use códigos de erro para tratamento programático

2. Registre erros com contexto

3. Trate erros em nível de campo

4. Implemente circuit breakers para integrações

5. Mantenha-se atualizado