Error Messages & Standardized Error Envelopes

// ✅ PRODUCTION PATTERN: RFC 7807 Global Exception Handling
@RestControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class);

    @ExceptionHandler(InsufficientInventoryException.class)
    public ProblemDetail handleInventoryError(InsufficientInventoryException ex, HttpServletRequest req) {
        String errorId = MDC.get("traceId");
        
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, 
            ex.getMessage() // Safe domain message: "Only 2 items remain in stock."
        );
        problem.setTitle("Inventory Shortage");
        problem.setType(URI.create("https://beingsde.in/errors/insufficient-inventory"));
        problem.setInstance(URI.create(req.getRequestURI()));
        problem.setProperty("error_id", errorId);
        problem.setProperty("available_quantity", ex.getAvailableQuantity());
        problem.setProperty("timestamp", Instant.now());
        
        return problem;
    }

    @ExceptionHandler(Exception.class)
    public ProblemDetail handleUnexpectedCrash(Exception ex, HttpServletRequest req) {
        String errorId = UUID.randomUUID().toString().substring(0, 8);
        log.error("Unhandled internal server crash: error_id={}", errorId, ex);
        
        // NEVER leak ex.getMessage() for unexpected 500s!
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.INTERNAL_SERVER_ERROR,
            "An unexpected server error occurred. Please quote error_id to support."
        );
        problem.setTitle("Internal Server Error");
        problem.setProperty("error_id", errorId);
        return problem;
    }
}