# Error Codes

Reference of HTTP status codes, BACEN error codes, and application-specific error responses.

## Prerequisites

- Understanding of RFC 7807 Problem Details format
- Familiarity with BACEN PIX error code system

## Error Response Format

All errors follow RFC 7807 (`application/problem+json`):

```json
{
  "type": "https://api.fluxiq.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The field 'amount' must be a positive integer in centavos",
  "instance": "/api/v1/transactions",
  "errors": [
    {
      "field": "amount",
      "message": "must be a positive integer"
    }
  ]
}
```

## HTTP Status Codes

| Status | Meaning | Common Causes |
|--------|---------|---------------|
| 200 | OK | Successful request |
| 201 | Created | Resource created |
| 400 | Bad Request | Invalid request body, missing fields |
| 401 | Unauthorized | Invalid/expired/blacklisted token |
| 403 | Forbidden | RBAC permission denied |
| 404 | Not Found | Resource does not exist |
| 409 | Conflict | Duplicate resource (idempotency) |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Unexpected server error |
| 503 | Service Unavailable | Circuit breaker open |

## BACEN Error Codes

161 BACEN error codes are seeded during migration. Common ones:

### DICT Errors

| Code | Description | HTTP Status |
|------|-------------|-------------|
| AB03 | Invalid account | 400 |
| AB09 | Account not found | 404 |
| AC03 | Invalid creditor account | 400 |
| AC06 | Account blocked | 422 |
| BE01 | Inconsistent with end customer | 400 |
| DT02 | Invalid date/time | 400 |
| ED05 | Settlement failed | 500 |
| FF07 | Invalid purpose | 400 |
| RC09 | Invalid file format | 400 |
| RUTA | Route not found | 404 |

### SPI Errors

| Code | Description | HTTP Status |
|------|-------------|-------------|
| AB03 | Account blocked | 422 |
| AB09 | Invalid account number | 400 |
| AC03 | Invalid creditor account | 400 |
| AC06 | Account closed | 422 |
| AG03 | Transaction not supported | 400 |
| AM02 | Amount exceeds limit | 422 |
| AM09 | Invalid amount | 400 |
| BE01 | Inconsistent end customer | 400 |
| DS04 | Order rejected | 422 |
| RC01 | Bank identifier incorrect | 400 |
| RR04 | Regulatory reason | 422 |

## Application Errors

### Authentication

| Error | Status | Detail |
|-------|--------|--------|
| `invalid_credentials` | 401 | Username or password incorrect |
| `account_blocked` | 401 | Account locked after 10 failed attempts |
| `account_inactive` | 401 | Account deactivated by admin |
| `token_expired` | 401 | JWT token has expired |
| `token_blacklisted` | 401 | Token revoked on logout |
| `mfa_required` | 401 | MFA verification needed |
| `invalid_mfa_code` | 401 | TOTP code incorrect |
| `rate_limited` | 429 | Too many login attempts (10/15min) |

### Authorization

| Error | Status | Detail |
|-------|--------|--------|
| `permission_denied` | 403 | User lacks required permission |
| `invalid_target_system` | 403 | SSO token target_system mismatch |

### Transactions

| Error | Status | Detail |
|-------|--------|--------|
| `duplicate_e2e_id` | 409 | End-to-End ID already exists |
| `insufficient_balance` | 422 | Insufficient settlement balance |
| `invalid_amount` | 422 | Amount must be positive integer (centavos) |
| `invalid_key` | 404 | PIX key not found in DICT |
| `idempotency_conflict` | 409 | Different body with same idempotency key |

### Infrastructure

| Error | Status | Detail |
|-------|--------|--------|
| `circuit_open` | 503 | Circuit breaker is open |
| `service_unavailable` | 503 | Downstream service unreachable |
| `nats_publish_failed` | 500 | Failed to publish NATS message |
| `db_connection_failed` | 500 | Database connection error |

## Error Lookup

`Shared.Bacen.ErrorLookup` provides runtime error code resolution:

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

The lookup table is cached in ETS with a 10-minute refresh interval.

## Expected Outcome

After reviewing this reference:

- Understanding of the RFC 7807 error response format
- Knowledge of common BACEN error codes and their meanings
- Application-specific error codes for authentication, transactions, and infrastructure