Códigos de Erro
Todos os erros da API seguem um formato padronizado com código, mensagem e request ID para rastreamento.
Formato de Erro
Resposta de erro padrãojson
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Token de autenticação expirado",
"statusCode": 401,
"timestamp": "2026-02-15T12:00:00.000Z",
"path": "/v1/auth/me",
"requestId": "550e8400-e29b-41d4-a716-446655440000"
}
}Códigos de Status HTTP
| Status | Código | Descrição |
|---|---|---|
| 200 | OK | Requisição bem-sucedida |
| 201 | CREATED | Recurso criado com sucesso |
| 204 | NO_CONTENT | Operação bem-sucedida sem corpo |
| 400 | BAD_REQUEST | Dados inválidos ou malformados |
| 401 | UNAUTHORIZED | Token ausente, inválido ou expirado |
| 403 | FORBIDDEN | Sem permissão para o recurso |
| 404 | NOT_FOUND | Recurso não encontrado |
| 409 | CONFLICT | Conflito (ex: email duplicado) |
| 422 | UNPROCESSABLE_ENTITY | Erro de validação nos dados |
| 429 | TOO_MANY_REQUESTS | Rate limit excedido |
| 500 | INTERNAL_ERROR | Erro interno do servidor |
Erros de Validação
Quando há erros de validação (422), o campo details contém a lista de problemas:
Erro de validaçãojson
{
"success": false,
"error": {
"code": "BAD_REQUEST",
"message": "Erro de validação",
"statusCode": 400
},
"details": [
"email must be an email",
"password must be longer than or equal to 8 characters",
"fullName must be longer than or equal to 2 characters"
]
}Códigos Especiais
TOKEN_EXPIREDO access token expirou. Use o refresh token para obter um novo.INVALID_TOKENToken JWT malformado ou com assinatura inválida.DATABASE_ERRORErro ao processar dados (unique constraint, foreign key, etc.)Modo Produção
Em produção, mensagens de erro detalhadas são ocultadas por segurança. Apenas o código e uma mensagem genérica são retornados. Use o
requestId para rastrear erros nos logs do servidor.