Tratamento de erros

​

Modelo de resposta de erro

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

• 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.

​

Detalhes de erro em nível de campo

{
   "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"
   }
}

​

Estrutura de códigos de erro

<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

​

Faixas de números

​

Classificação de erros

​

Erros de validação

• 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

​

Erros de lógica de negócio

• 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

​

Erros de sistema

• 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

​

Códigos de status HTTP

​

Orientação de retentativas

​

Estratégia de backoff exponencial

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

​

Resolução de problemas por categoria

​

Campos ausentes ou inválidos (400)

• 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

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

​

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

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

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

​

Recurso não encontrado (404)

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

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

​

Erros de conflito (409)

• 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)

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

​

Limite de taxa (429)

• Muitas requisições em um período curto

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

​

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

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

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

​

Listas de erros por serviço

​

Boas práticas

​

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

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

​

3. Trate erros em nível de campo

​

4. Implemente circuit breakers para integrações

​

5. Mantenha-se atualizado