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

> Saiba como interpretar e resolver as respostas de erro retornadas pelas APIs da Lerian, incluindo os envelopes de erro, códigos de status HTTP e detalhes por campo.

Este guia explica o formato de uma resposta de erro da Lerian e como responder a cada tipo.

## O que você vai receber

***

Uma resposta `application/problem+json` é um objeto problem details do [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). A referência da sua API traz uma página **Tratamento de erros** que nomeia o formato que aquela API responde.

```json application/problem+json theme={null}
{
  "type": "https://errors.lerian.studio/v1/RPT-0012",
  "title": "Bad Request",
  "status": 400,
  "detail": "The specified templateID is not a valid UUID. Please check the value passed.",
  "code": "RPT-0012"
}
```

```json application/json theme={null}
{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}
```

**Definições de campo**

No objeto problem details:

* **`type`** – Uma referência URI que identifica o tipo do erro.
* **`title`** – Um resumo curto do tipo de problema.
* **`status`** – O código de status HTTP.
* **`detail`** – Orientação específica dessa ocorrência.
* **`errors`** – Lista opcional de detalhe por campo, cada item com um `location` e uma `message`.
* **`instance`** – Referência URI opcional para essa ocorrência específica.

Envelopes simples diferem entre as APIs. Diferem no nome dos campos, em se o erro fica no nível superior,
e em qual campo carrega o token legível por máquina. Leia a página **Tratamento de erros** da referência da sua API antes de escrever um parser.

> [!TIP]
>
> Onde uma API publica um código estável, ramifique a partir dele. Nem toda API publica um código, e a página dela de
> **Tratamento de erros** diz se publica.

## Códigos de erro

***

O formato do código varia por API. Você vai encontrar um `<PREFIX>-<NNNN>` com prefixo, um número puro, um
token em minúsculas e um código que a contraparte de um trilho atribuiu. O core do Midaz usa números puros como `0002`
e `0009`.

A referência da sua API traz uma página **Tratamento de erros** que nomeia o formato que aquela API usa e lista
os códigos que ela emite.

## Códigos de status HTTP

***

Estes são os códigos de status que você vai encontrar com mais frequência. Uma API pode responder outros, e a própria página **Tratamento de erros** dela os lista.

| Código | Significado |
| - | - |
| `400` | Bad Request |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found |
| `409` | Conflict |
| `422` | Unprocessable Entity |
| `412` | Precondition Failed |
| `413` | Payload Too Large |
| `429` | Too Many Requests |
| `500` | Internal Server Error |
| `502` | Bad Gateway |
| `501` | Not Implemented |
| `503` | Service Unavailable |
| `504` | Gateway Timeout |

## Orientação de nova tentativa

***

Você não deve tentar de novo todo erro. A tabela a seguir ajuda você a decidir:

| Tipo de erro | Repetível | Ação recomendada |
| - | - | - |
| `400` | Não | Corrija o payload da requisição |
| `401` | Depois de renovar o token | Verifique as credenciais |
| `403` | Não | Verifique as permissões |
| `404` não encontrado | Não | Verifique o ID do recurso |
| Conflitos `409` | Às vezes | Verifique o estado atual e tente de novo se o conflito estiver resolvido |
| `422` | Não | Corrija a causa que o erro indica |
| `429` limite de taxa | Às vezes | Aguarde e tente de novo as leituras. Concilie os comandos antes de tentar de novo. |
| Erros internos `500` | Às vezes | Tente de novo as leituras com backoff exponencial. Concilie os comandos antes de tentar de novo. |
| `502` / `503` / `504` | Às vezes | Tente de novo as leituras com backoff exponencial. Concilie os comandos antes de tentar de novo. |

> [!WARNING]
>
> Um comando que falhou pode ter um resultado desconhecido. Para comandos, siga a referência dessa API para saber qual chave de idempotência usar. Algumas APIs exigem a chave original, enquanto outras a rejeitam ou descartam depois de um resultado incerto do provedor.

### Estratégia de backoff exponencial

Para erros repetíveis, use backoff exponencial para evitar sobrecarregar o serviço:

1. **Primeira tentativa**: aguarde 1 segundo
2. **Segunda tentativa**: aguarde 2 segundos
3. **Terceira tentativa**: aguarde 4 segundos
4. **Máximo de tentativas**: pare depois de 3–5 tentativas
5. **Jitter**: adicione um pequeno atraso aleatório (0–500ms) a cada espera para evitar thundering herd

> [!WARNING]
>
> Não repita um `400`, um `403` ou um `422` sem alterações. Um `401` vale uma nova tentativa depois de você renovar o token, e não mais que isso.

## Solução de problemas por categoria

***

### Campos ausentes ou inválidos (400)

Uma resposta `400` pode carregar detalhe por campo que nomeia os campos com problema.

**Causas comuns:**

* Campo obrigatório omitido do corpo da requisição
* Valor do campo não corresponde ao tipo esperado (por exemplo, string em vez de UUID)
* Valor do campo excede o tamanho máximo
* Campos extras inesperados no corpo da requisição

**Passos de resolução:**

1. Leia o detalhe por campo na resposta de erro
2. Compare sua requisição com a referência da API para esse endpoint

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

**Causas comuns:**

* Credencial ausente
* Token expirado ou revogado
* O token não concede acesso ao endpoint solicitado

**Passos de resolução:**

1. Verifique se a requisição traz a credencial que sua API espera
2. Solicite um novo token se o atual expirou
3. Verifique se quem chama tem as permissões exigidas

### Recurso não encontrado (404)

**Causas comuns:**

* ID de recurso incorreto no caminho da URL
* Recurso removido de forma lógica (soft delete)
* Recurso pertence a uma organização ou ledger diferente

**Passos de resolução:**

1. Verifique o ID do recurso no caminho da URL
2. Liste os recursos para confirmar que o ID existe

### Erros de conflito (409)

**Causas comuns:**

* Criar um recurso com um nome que já existe (por exemplo, nome de ledger duplicado, nome de regra duplicado)
* Tentar uma operação que já está completa (por exemplo, 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 (por exemplo, renomeie) ou recupere o recurso existente
3. Para operações idempotentes, verifique se o recurso existente corresponde à sua intenção

### Limitação 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 das chamadas de API
3. Agrupe operações em lote quando 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 de novo as leituras com backoff exponencial (1s, 2s, 4s). Concilie os comandos antes de tentar de novo, porque o resultado original pode ser desconhecido.
2. Se o erro persistir depois de 3–5 novas tentativas, contate o suporte
3. Registre uma resposta de erro com dados sensíveis removidos para a escalação ao suporte

## Listas de erros por serviço

***

Toda referência de API traz uma página **Tratamento de erros**. Use-a para consultar um código que você recebeu.

**Produtos**

| API | Lista de erros |
| - | - |
| Midaz | [Lista de erros do Midaz](https://docs.lerian.studio/pt/reference/products/midaz/error-list.md) |
| Tracer | [Lista de erros do Tracer](https://docs.lerian.studio/pt/reference/products/tracer/tracer-error-list.md) |
| Matcher | [Lista de erros do Matcher](https://docs.lerian.studio/pt/reference/products/matcher/matcher-error-list.md) |
| Flowker | [Lista de erros do Flowker](https://docs.lerian.studio/pt/reference/products/flowker/flowker-error-list.md) |
| Lender | [Lista de erros do Lender](https://docs.lerian.studio/pt/reference/products/lender/lender-error-list.md) |
| Reporter | [Lista de erros do Reporter](https://docs.lerian.studio/pt/reference/products/reporter/reporter-error-list.md) |

**Trilhos Brasil**

| API | Lista de erros |
| - | - |
| SPB (TED) | [Lista de erros do SPB](https://docs.lerian.studio/pt/reference/rails/spb/spb-error-list.md) |
| SPI (Pix) | [Lista de erros do SPI](https://docs.lerian.studio/pt/reference/rails/spi/spi-error-list.md) |
| SLC | [Lista de erros do SLC](https://docs.lerian.studio/pt/reference/rails/slc/slc-error-list.md) |
| SILOC | [Lista de erros do SILOC](https://docs.lerian.studio/pt/reference/rails/siloc/siloc-error-list.md) |
| STA | [Lista de erros do STA](https://docs.lerian.studio/pt/reference/rails/sta/sta-error-list.md) |
| SISBAJUD | [Lista de erros do SISBAJUD](https://docs.lerian.studio/pt/reference/rails/sisbajud/sisbajud-error-list.md) |
| BC Correios | [Lista de erros do BC Correios](https://docs.lerian.studio/pt/reference/rails/bc-correios/bc-correios-error-list.md) |
| SRC | [Lista de erros do SRC](https://docs.lerian.studio/pt/reference/rails/src/src-error-list.md) |
| Consignado CLT (Dataprev) | [Lista de erros do Consignado](https://docs.lerian.studio/pt/reference/rails/consignado/consignado-error-list.md) |

**Interfaces**

| API | Lista de erros |
| - | - |
| Pix Lerian | [Lista de erros do Pix Lerian](https://docs.lerian.studio/pt/reference/interfaces/pix-lerian/pix-lerian-error-list.md) |
| Pix JD | [Lista de erros do Pix JD](https://docs.lerian.studio/pt/reference/interfaces/pix-jd/pix-jd-error-list.md) |
| Pix BTG | [Lista de erros do Pix BTG](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/indirect-pix-error-list.md) |
| TED JD | [Lista de erros do TED JD](https://docs.lerian.studio/pt/reference/interfaces/ted-jd/ted-error-list.md) |
| Payments BTG | [Lista de erros do Payments](https://docs.lerian.studio/pt/reference/interfaces/payments-btg/payments-error-list.md) |

**Plataforma**

| API | Lista de erros |
| - | - |
| Access Manager | [Lista de erros do Access Manager](https://docs.lerian.studio/pt/reference/platform/access-manager/access-manager-error-list.md) |
| Streaming Hub | [Lista de erros do Streaming Hub](https://docs.lerian.studio/pt/reference/platform/streaming-hub/streaming-hub-error-list.md) |
| Systemplane | [Lista de erros do Systemplane](https://docs.lerian.studio/pt/reference/platform/systemplane/systemplane-error-list.md) |
| Narya | [Lista de erros da API host do Narya](https://docs.lerian.studio/pt/reference/platform/narya/host-api-error-list.md) |

## Boas práticas

***

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

Códigos de erro são identificadores estáveis para automação. Mapeie códigos específicos para caminhos de resolução na sua integração. Tire os códigos da página de lista de erros da sua API.

### 2. Registre erros com contexto

Registre a operação, o timestamp, o status, o código de erro estável e uma resposta com dados sensíveis removidos. Não registre credenciais, bearer tokens, dados pessoais ou campos sensíveis da requisição. Isso mantém o contexto útil para o suporte sem copiar segredos ou PII para os logs.

### 3. Trate erros por campo

Quando a resposta carrega detalhe por campo, mostre essas mensagens aos seus usuários em vez de um erro genérico. O membro que carrega esse detalhe difere por API. Cada página de lista de erros nomeia o membro que a API dela envia.

### 4. Implemente circuit breakers para integrações

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

### 5. Mantenha-se atualizado

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.