> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Tratamento de erros

> Como interpretar, classificar e resolver erros retornados pelas APIs da Lerian.

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:

```json theme={null}
{
   "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.

<Tip>
  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.
</Tip>

### 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:

<CodeGroup>
  ```json Campos obrigatórios ausentes theme={null}
  {
     "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"
     }
  }
  ```

  ```json Valores de campo inválidos theme={null}
  {
     "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"
     }
  }
  ```

  ```json Campos inesperados theme={null}
  {
     "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"
     }
  }
  ```
</CodeGroup>

## 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                        |

<Note>
  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.
</Note>

### 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:

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

<Warning>
  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.
</Warning>

## 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:**

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)

**Causas comuns:**

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

**Passos de resolução:**

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)

**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:**

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)

**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:**

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)

**Causas comuns:**

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

**Passos de resolução:**

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)

**Causas comuns:**

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

**Passos de resolução:**

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

***

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](/pt/reference/midaz/error-list)                                      |
| Access Manager      | [Lista de erros do Access Manager](/pt/reference/access-manager/access-manager-error-list)     |
| CRM                 | [Lista de erros do CRM](/pt/reference/midaz/crm/crm-error-list)                                |
| Fees Engine         | [Lista de erros do Fees Engine](/pt/reference/midaz/plugins/fees-engine/fee-engine-error-list) |
| Bank Transfer (TED) | [Lista de erros do TED](/pt/reference/midaz/plugins/ted/ted-error-list)                        |
| Reporter            | [Lista de erros do Reporter](/pt/reference/reporter/reporter-error-list)                       |
| Tracer              | [Lista de erros do Tracer](/pt/reference/tracer/tracer-error-list)                             |

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