# ADR 003 — Códigos de erro padronizados na API

## Status

Aceito (2025-03)

## Contexto

A API v2 retornava erros em formatos variados: `{ "error": "..." }` sem código padronizado, dificultando tratamento programático no frontend.

## Decisão

Padronizar respostas de erro no formato:

```json
{
  "code": "ERROR_CODE",
  "message": "Mensagem legível"
}
```

**Códigos definidos (ApiError):**

| Código | HTTP | Uso |
|--------|------|-----|
| VALIDATION_ERROR | 400 | Dados inválidos |
| BAD_REQUEST | 400 | Requisição malformada |
| UNAUTHORIZED | 401 | Não autenticado |
| NOT_FOUND | 404 | Recurso não encontrado |
| METHOD_NOT_ALLOWED | 405 | Método HTTP não permitido |
| INTERNAL_ERROR | 500 | Erro interno |

**Adoção gradual:** Router usa ApiError; controllers podem migrar ao longo do tempo.

## Consequências

- Frontend pode tratar erros por `code` além do status HTTP
- Documentação OpenAPI pode referenciar códigos
- Retrocompatibilidade: clientes que usam `error` podem migrar para `message`

## Referências

- api/src/Http/ApiError.php
- api/src/Http/Router.php
- ideias-melhorias.md §9