Erros e convenções
Códigos de status, formato de erro, paginação e cabeçalhos comuns.
Convenções gerais
- Base path: rotas de usuário sob
/api, rotas de serviço sob/service. - Autenticação: sempre
Authorization: Bearer <jwt>. - Content-Type:
application/jsonem requisições com corpo. - Datas: ISO 8601 em UTC (ex.:
2026-07-10T12:00:00.000Z). - IDs: UUID v4.
Códigos de status
| Status | Quando ocorre |
|---|---|
200 | Leitura/edição bem-sucedida. |
201 | Criação bem-sucedida (POST). |
204 | Remoção bem-sucedida (DELETE), sem corpo. |
400 | Falha de validação (Zod) do corpo ou query string. |
401 | Token ausente, inválido ou expirado. |
403 | Autenticado, mas sem a permissão exigida (NotAllowedError). |
404 | Recurso não encontrado (ResourceNotFoundError). |
409 | Conflito de unicidade (ex.: email/federalTaxId já existente). |
Formato de erro
Erros seguem o formato padrão do NestJS HttpException:
{
"statusCode": 409,
"message": "Já existe um usuário com esse email",
"error": "Conflict"
}Erros de validação Zod (400) trazem o detalhamento dos campos inválidos no
campo message.
Paginação
Endpoints de listagem (GET de coleção) aceitam os query params:
| Param | Tipo | Padrão | Regras |
|---|---|---|---|
page | number | 1 | inteiro, mín. 1 |
limit | number | 20 | inteiro, 1 a 100 |
E respondem no envelope:
{
"data": [],
"total": 0,
"totalPages": 0,
"currentPage": 1
}Filtros adicionais (ex.: name, email, type) são específicos de cada
recurso e estão descritos na respectiva página de endpoints.