Tratamento de Erros

A API retorna erros padronizados no formato JSON com detalhes suficientes para depuração.

Formato padrão de erro

{
  "error": "Descrição curta do erro",
  "details": "Detalhes adicionais (opcional)",
  "statusCode": 400
}

Para erros de validação (400), a resposta inclui os campos com problema:

{
  "errors": {
    "Code": ["O campo Code é obrigatório."],
    "SalePrice": ["O valor deve ser maior que zero."]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400
}

---

Códigos HTTP utilizados

200 OK

Requisição bem-sucedida. Retorna o recurso solicitado ou lista paginada.

{
  "data": [...],
  "page": 1,
  "pageSize": 20,
  "total": 45,
  "totalPages": 3
}

201 Created

Recurso criado com sucesso. O objeto criado é retornado no body.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "AP-001",
  "status": "Available",
  "createdAt": "2026-05-19T10:30:00Z"
}

400 Bad Request

Dados inválidos. Ocorre quando validações de campos falham.

Causas comuns:

• Campo obrigatório ausente
• Tipo de dado incorreto
• Valor fora do intervalo permitido
• Formato inválido (ex: CPF malformado)

{
  "errors": {
    "Email": ["Email inválido."],
    "Phone": ["O campo Phone é obrigatório."]
  },
  "status": 400
}

401 Unauthorized

Token de autenticação ausente, expirado ou inválido.

{
  "error": "Token inválido ou expirado.",
  "statusCode": 401
}

Ação no frontend: o errorInterceptor redireciona automaticamente para /login.

403 Forbidden

Usuário autenticado, mas sem permissão para o recurso.

{
  "error": "Você não tem permissão para realizar esta ação.",
  "statusCode": 403
}

Ação no frontend: exibe mensagem de "Acesso negado" sem redirecionar.

404 Not Found

O recurso solicitado não existe (ou foi deletado com soft delete).

{
  "error": "Imóvel não encontrado.",
  "statusCode": 404
}

409 Conflict

Conflito com um recurso existente.

Casos comuns:

• CNPJ já cadastrado
• E-mail já em uso
• Código de imóvel duplicado na empresa

{
  "error": "Já existe um imóvel com o código AP-001 nesta empresa.",
  "statusCode": 409
}

422 Unprocessable Entity

A requisição é válida sintaticamente, mas viola uma regra de negócio.

Casos comuns:

• Tentar aprovar uma proposta expirada
• Converter proposta não aprovada em contrato
• Alterar status inválido de imóvel

{
  "error": "Proposta expirada não pode ser aprovada.",
  "statusCode": 422
}

500 Internal Server Error

Erro inesperado no servidor.

{
  "error": "Ocorreu um erro interno. Tente novamente.",
  "statusCode": 500
}

Ação no frontend: o errorInterceptor exibe mensagem genérica de erro.

---

Tratamento no Angular

O errorInterceptor centraliza o tratamento de todos os erros HTTP:

// error.interceptor.ts
export const errorInterceptor: HttpInterceptorFn = (req, next) => {
  return next(req).pipe(
    catchError((error: HttpErrorResponse) => {
      switch (error.status) {
        case 401:
          router.navigate(['/login']);
          break;
        case 403:
          toastService.error('Acesso negado. Você não tem permissão para esta ação.');
          break;
        case 500:
          toastService.error('Erro interno do servidor. Tente novamente.');
          break;
      }
      return throwError(() => error);
    })
  );
};

---

Timeout de requisição

O timeoutInterceptor cancela requisições que ultrapassem 30 segundos:

// Pode ser customizado via token de injeção
providers: [
  { provide: REQUEST_TIMEOUT, useValue: 60_000 } // 60 segundos
]

Quando o timeout é atingido, um TimeoutError é lançado e tratado pelo errorInterceptor.

---

Logs de erros

Em ambiente de desenvolvimento, o loggingInterceptor registra todas as requisições e respostas no console do navegador, incluindo erros com stack trace.

No backend, o Serilog registra erros com nível Error e exceções com contexto de request.