# Codigos de Erro

Referencia de codigos de status HTTP, codigos de erro BACEN e respostas de erro especificas da aplicacao.

## Pre-requisitos

- Compreensao do formato RFC 7807 Problem Details
- Familiaridade com o sistema de codigos de erro PIX do BACEN

## Formato de Resposta de Erro

Todos os erros seguem RFC 7807 (`application/problem+json`):

```json
{
  "type": "https://api.fluxiq.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "O campo 'amount' deve ser um inteiro positivo em centavos",
  "instance": "/api/v1/transactions",
  "errors": [
    {
      "field": "amount",
      "message": "deve ser um inteiro positivo"
    }
  ]
}
```

## Codigos de Status HTTP

| Status | Significado | Causas Comuns |
|--------|-------------|---------------|
| 200 | OK | Requisicao bem-sucedida |
| 201 | Created | Recurso criado |
| 400 | Bad Request | Corpo da requisicao invalido, campos ausentes |
| 401 | Unauthorized | Token invalido/expirado/revogado |
| 403 | Forbidden | Permissao RBAC negada |
| 404 | Not Found | Recurso nao encontrado |
| 409 | Conflict | Recurso duplicado (idempotencia) |
| 422 | Unprocessable Entity | Erros de validacao |
| 429 | Too Many Requests | Limite de taxa excedido |
| 500 | Internal Server Error | Erro inesperado do servidor |
| 503 | Service Unavailable | Circuit breaker aberto |

## Codigos de Erro BACEN

161 codigos de erro BACEN sao populados durante a migracao. Os mais comuns:

### Erros DICT

| Codigo | Descricao | Status HTTP |
|--------|-----------|-------------|
| AB03 | Conta invalida | 400 |
| AB09 | Conta nao encontrada | 404 |
| AC03 | Conta do credor invalida | 400 |
| AC06 | Conta bloqueada | 422 |
| BE01 | Inconsistente com cliente final | 400 |
| DT02 | Data/hora invalida | 400 |
| ED05 | Falha na liquidacao | 500 |
| FF07 | Finalidade invalida | 400 |
| RC09 | Formato de arquivo invalido | 400 |
| RUTA | Rota nao encontrada | 404 |

### Erros SPI

| Codigo | Descricao | Status HTTP |
|--------|-----------|-------------|
| AB03 | Conta bloqueada | 422 |
| AB09 | Numero de conta invalido | 400 |
| AC03 | Conta do credor invalida | 400 |
| AC06 | Conta encerrada | 422 |
| AG03 | Transacao nao suportada | 400 |
| AM02 | Valor excede o limite | 422 |
| AM09 | Valor invalido | 400 |
| BE01 | Cliente final inconsistente | 400 |
| DS04 | Ordem rejeitada | 422 |
| RC01 | Identificador do banco incorreto | 400 |
| RR04 | Razao regulatoria | 422 |

## Erros da Aplicacao

### Autenticacao

| Erro | Status | Detalhe |
|------|--------|---------|
| `invalid_credentials` | 401 | Usuario ou senha incorretos |
| `account_blocked` | 401 | Conta bloqueada apos 10 tentativas falhas |
| `account_inactive` | 401 | Conta desativada pelo administrador |
| `token_expired` | 401 | Token JWT expirado |
| `token_blacklisted` | 401 | Token revogado no logout |
| `mfa_required` | 401 | Verificacao MFA necessaria |
| `invalid_mfa_code` | 401 | Codigo TOTP incorreto |
| `rate_limited` | 429 | Muitas tentativas de login (10/15min) |

### Autorizacao

| Erro | Status | Detalhe |
|------|--------|---------|
| `permission_denied` | 403 | Usuario nao possui permissao necessaria |
| `invalid_target_system` | 403 | target_system do token SSO nao corresponde |

### Transacoes

| Erro | Status | Detalhe |
|------|--------|---------|
| `duplicate_e2e_id` | 409 | End-to-End ID ja existe |
| `insufficient_balance` | 422 | Saldo de liquidacao insuficiente |
| `invalid_amount` | 422 | Valor deve ser inteiro positivo (centavos) |
| `invalid_key` | 404 | Chave PIX nao encontrada no DICT |
| `idempotency_conflict` | 409 | Corpo diferente com mesma chave de idempotencia |

### Infraestrutura

| Erro | Status | Detalhe |
|------|--------|---------|
| `circuit_open` | 503 | Circuit breaker esta aberto |
| `service_unavailable` | 503 | Servico downstream indisponivel |
| `nats_publish_failed` | 500 | Falha ao publicar mensagem NATS |
| `db_connection_failed` | 500 | Erro de conexao com banco de dados |

## Consulta de Erros

`Shared.Bacen.ErrorLookup` fornece resolucao de codigos de erro em tempo de execucao:

```elixir
# Consulta por codigo BACEN
ErrorLookup.get_error("AB03")
# => %{code: "AB03", description: "Account blocked", category: "account"}
```

A tabela de consulta e armazenada em cache ETS com intervalo de atualizacao de 10 minutos.

## Resultado Esperado

Apos revisar esta referencia:

- Compreensao do formato de resposta de erro RFC 7807
- Conhecimento dos codigos de erro BACEN comuns e seus significados
- Codigos de erro especificos da aplicacao para autenticacao, transacoes e infraestrutura