Skip to content

19 – Manejo global de excepciones y respuestas HTTP coherentes

Descripción

Centralizar el manejo de errores con @RestControllerAdvice para que todos los endpoints devuelvan una estructura de error estándar sin exponer detalles internos.

Owner sugerido: Dev A | Branch: feature/global-exception-handler | Depende de: #11 (closed)

Tareas

  • Crear ApiErrorResponse record en dto/response/: timestamp, status, error, message, path, List<FieldErrorItem>.
  • Crear GlobalExceptionHandler en exception/ con @RestControllerAdvice:
    • MethodArgumentNotValidException → 400 con detalle de campos
    • ConstraintViolationException → 400
    • EstudianteNotFoundException → 404
    • CedulaDuplicadaException, EstudianteInactivoException → 409
    • Exception → 500 (log con ERROR, body genérico sin stack trace)
  • No exponer stack traces al cliente (OWASP A05).
  • Loguear WARN en 4xx y ERROR con stack en 5xx.
  • Documentar schema en Swagger con @ApiResponse + @Schema(implementation = ApiErrorResponse.class).

Commits sugeridos

feat(error): definir DTO estándar de respuesta de error
feat(error): agregar GlobalExceptionHandler con mappings 400/404/409/500
chore(security): no exponer stack traces en respuestas de error

Criterios de aceptación

  • Todos los errores responden con ApiErrorResponse.
  • 400 lista campos con problemas.
  • Logs registran detalle sin exponerlo al cliente.
  • Swagger documenta el schema del error.

Referencia del curso: Módulo 1 – PDF 5; Módulo 2 – PDFs 1, 8