Problem Details RFC 9457 — error response chuẩn hoá

{ "error": "not_found", "msg": "Order 42 not found" }
{ "success": false, "message": "Order not found", "code": 404 }
{ "status": 404, "errorMessage": "Not found", "errorCode": "E004" }

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "https://api.olhub.org/errors/order-not-found",
  "title": "Order not found",
  "status": 404,
  "detail": "Order 42 was not found or has been deleted",
  "instance": "/api/v1/orders/42",
  "orderId": 42,
  "timestamp": "2026-06-09T08:00:00Z"
}

spring:
  mvc:
    problemdetails:
      enabled: true

// Tao ProblemDetail voi status code
ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);

// Tao voi status + detail message ngay
ProblemDetail pd = ProblemDetail.forStatusAndDetail(
    HttpStatus.NOT_FOUND,
    "Order 42 was not found"
);

// Set cac truong chuan
pd.setType(URI.create("https://api.olhub.org/errors/order-not-found"));
pd.setTitle("Order not found");
pd.setInstance(URI.create("/api/v1/orders/42"));

// Add extension member (custom field)
pd.setProperty("orderId", 42L);
pd.setProperty("timestamp", Instant.now());
pd.setProperty("retryAfter", 30);

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // Domain exception: not found -> 404
    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleOrderNotFound(OrderNotFoundException ex,
                                              HttpServletRequest req) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        pd.setType(URI.create("https://api.olhub.org/errors/order-not-found"));
        pd.setTitle("Order not found");
        pd.setDetail(ex.getMessage());
        pd.setInstance(URI.create(req.getRequestURI()));
        pd.setProperty("orderId", ex.getOrderId());
        return pd;
    }

    // Conflict -> 409
    @ExceptionHandler(DuplicateOrderException.class)
    public ProblemDetail handleDuplicate(DuplicateOrderException ex,
                                          HttpServletRequest req) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.CONFLICT);
        pd.setTitle("Duplicate order");
        pd.setDetail(ex.getMessage());
        pd.setInstance(URI.create(req.getRequestURI()));
        return pd;
    }

    // Validation -> 400 voi danh sach violations
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ProblemDetail handleValidation(MethodArgumentNotValidException ex,
                                           HttpServletRequest req) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        pd.setType(URI.create("https://api.olhub.org/errors/validation"));
        pd.setTitle("Validation failed");
        pd.setDetail("Request has " + ex.getBindingResult().getErrorCount() + " invalid fields");
        pd.setInstance(URI.create(req.getRequestURI()));

        List<Map<String, Object>> violations = ex.getBindingResult().getFieldErrors().stream()
            .map(err -> {
                Map<String, Object> v = new LinkedHashMap<>();
                v.put("field", err.getField());
                v.put("message", err.getDefaultMessage());
                v.put("rejectedValue", err.getRejectedValue());
                return v;
            })
            .toList();
        pd.setProperty("violations", violations);
        return pd;
    }

    // Catch-all -> 500, KHONG leak detail
    @ExceptionHandler(Exception.class)
    public ProblemDetail handleAll(Exception ex, HttpServletRequest req) {
        String requestId = MDC.get("requestId");
        log.error("Unhandled exception, requestId={}, path={}",
            requestId, req.getRequestURI(), ex);  // log SERVER-side day du

        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
        pd.setTitle("Internal server error");
        pd.setDetail("An unexpected error occurred. Contact support with the request ID.");
        pd.setInstance(URI.create(req.getRequestURI()));
        pd.setProperty("requestId", requestId);   // client dung requestId de lien he support
        return pd;
    }
}

// ANTI-PATTERN: KHONG bao gio dung
@ExceptionHandler(Exception.class)
public ProblemDetail handleAll(Exception ex) {
    ProblemDetail pd = ProblemDetail.forStatus(500);
    pd.setDetail(ex.getMessage());                               // co the chua PII / schema
    pd.setProperty("stackTrace", ExceptionUtils.getStackTrace(ex));  // leak architecture
    return pd;
}

// DUNG: log server, response generic
@ExceptionHandler(Exception.class)
public ProblemDetail handleAll(Exception ex, HttpServletRequest req) {
    String requestId = MDC.get("requestId");
    // Full stack trace chi o server log, khong di vao response
    log.error("Unhandled exception, requestId={}", requestId, ex);

    ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.INTERNAL_SERVER_ERROR);
    pd.setTitle("Internal server error");
    pd.setDetail("An unexpected error occurred. Contact support with the request ID.");
    pd.setProperty("requestId", requestId);
    return pd;
}

# application-prod.yml
server:
  error:
    include-stacktrace: never    # PROD: tuyet doi khong expose
    include-message: never
    include-binding-errors: never

# application-dev.yml
server:
  error:
    include-stacktrace: on_param   # dev: ?trace=true -> hien (chi noi bo)
    include-message: always
    include-binding-errors: always

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    // Override method co san trong base class
    @Override
    protected ResponseEntity<Object> handleMethodArgumentNotValid(
            MethodArgumentNotValidException ex,
            HttpHeaders headers,
            HttpStatusCode status,
            WebRequest request) {

        ProblemDetail pd = ex.getBody();  // lay ProblemDetail da co san
        pd.setType(URI.create("https://api.olhub.org/errors/validation"));

        List<Map<String, Object>> violations = ex.getBindingResult().getFieldErrors().stream()
            .map(err -> Map.of(
                "field", err.getField(),
                "message", err.getDefaultMessage()
            ))
            .toList();
        pd.setProperty("violations", violations);

        return ResponseEntity.status(status).body(pd);
    }

    // Them handler cho domain exception
    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handleOrderNotFound(OrderNotFoundException ex,
                                              HttpServletRequest req) {
        ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.NOT_FOUND);
        pd.setTitle("Order not found");
        pd.setDetail(ex.getMessage());
        pd.setProperty("orderId", ex.getOrderId());
        return pd;
    }
}

@WebMvcTest(OrderController.class)
@Import(GlobalExceptionHandler.class)
class OrderExceptionHandlerTest {

    @Autowired MockMvc mockMvc;
    @MockitoBean OrderService orderService;

    @Test
    void orderNotFound_returns404WithProblemDetail() throws Exception {
        when(orderService.findById(99L))
            .thenThrow(new OrderNotFoundException(99L));

        mockMvc.perform(get("/api/v1/orders/99"))
            .andExpect(status().isNotFound())
            .andExpect(content().contentType("application/problem+json"))
            .andExpect(jsonPath("$.title").value("Order not found"))
            .andExpect(jsonPath("$.status").value(404))
            .andExpect(jsonPath("$.detail").value("Order 99 was not found"))
            .andExpect(jsonPath("$.instance").value("/api/v1/orders/99"))
            .andExpect(jsonPath("$.orderId").value(99));
    }

    @Test
    void serverError_doesNotLeakInternals() throws Exception {
        when(orderService.findById(any()))
            .thenThrow(new RuntimeException(
                "DB error: user_email='[email protected]' schema=orders_db"));

        String body = mockMvc.perform(get("/api/v1/orders/1"))
            .andExpect(status().isInternalServerError())
            .andExpect(jsonPath("$.requestId").exists())
            .andReturn().getResponse().getContentAsString();

        // Verify khong leak thong tin noi bo
        assertThat(body).doesNotContain("[email protected]");
        assertThat(body).doesNotContain("orders_db");
        assertThat(body).doesNotContain("stackTrace");
    }
}

# THIEU: Spring Boot 3.0-3.3 can set thu cong
spring:
  mvc:
    problemdetails:
      enabled: true

// SAI: method return ProblemDetail nhung KHONG co @ResponseBody
@ControllerAdvice
public class GlobalHandler {
    @ExceptionHandler(OrderNotFoundException.class)
    public ProblemDetail handle(OrderNotFoundException ex) { ... }
}

{ "type": "https://api.olhub.org/errors/order-not-found" }