How do you design REST error responses properly, and why is returning 200 OK with {"success": false} an anti-pattern

// Anti-pattern: 200 for everything, error hidden in body.
@PostMapping("/transfers")
public Map<String, Object> transfer(@RequestBody TransferRequest req) {
    try {
        transferService.create(req);
        return Map.of("success", true);
    } catch (Exception e) {
        return Map.of("success", false, "error", e.getMessage()); // 200 + error!
    }
}
// Problem: monitoring stays green, clients don't trigger error paths,
// retry logic never retries, caches may cache the "error" response.

// Correct: each failure maps to the right status code.
// InsufficientFundsException  → 422 Unprocessable Entity
// AccountNotFoundException     → 404 Not Found
// DuplicateAccountException    → 409 Conflict
// MethodArgumentNotValid       → 400 Bad Request
// AuthenticationException      → 401 Unauthorized
// AccessDeniedException        → 403 Forbidden

package com.bank.exception;

import java.time.Instant;

public record ApiError(
        String code,        // STABLE: "INSUFFICIENT_FUNDS" – clients switch on this
        String message,     // Human-readable, can change or be localised
        String traceId,     // Correlation id to find logs
        Instant timestamp   // When the error occurred
) {}

// Client code switches on the stable code, not the message.
if ("INSUFFICIENT_FUNDS".equals(error.code())) {
    showAddMoneyButton();
}
// The message can change from "Insufficient funds" to "Your balance is too low"
// without breaking any client.

// Trace id in the response: customer can share it with support.
// {
//   "code": "INSUFFICIENT_FUNDS",
//   "message": "Balance 250000 is less than requested 900000",
//   "traceId": "a1b2c3d4-e5f6-7890",
//   "timestamp": "2026-03-15T10:30:00Z"
// }

// Stack trace in the logs (NOT in the response):
// [traceId=a1b2c3d4] InsufficientFundsException: Balance 250000 < 900000
//   at com.bank.service.TransferService.validate(TransferService.java:45)

package com.bank.exception;

import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
import org.slf4j.MDC;
import java.time.Instant;

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(InsufficientFundsException.class)
    public ResponseEntity<ApiError> handleInsufficient(InsufficientFundsException e) {
        return buildError("INSUFFICIENT_FUNDS", e.getMessage(),
                HttpStatus.UNPROCESSABLE_ENTITY);
    }

    @ExceptionHandler(AccountNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(AccountNotFoundException e) {
        return buildError("ACCOUNT_NOT_FOUND", e.getMessage(),
                HttpStatus.NOT_FOUND);
    }

    @ExceptionHandler(DuplicateAccountException.class)
    public ResponseEntity<ApiError> handleConflict(DuplicateAccountException e) {
        return buildError("DUPLICATE_ACCOUNT", e.getMessage(),
                HttpStatus.CONFLICT);
    }

    private ResponseEntity<ApiError> buildError(String code, String message,
                                                 HttpStatus status) {
        ApiError error = new ApiError(code, message,
                MDC.get("traceId"), Instant.now());
        return ResponseEntity.status(status).body(error);
    }
}

// RFC 9457 Problem Details via Spring's ProblemDetail.
@ExceptionHandler(InsufficientFundsException.class)
public ProblemDetail handle(InsufficientFundsException e) {
    ProblemDetail pd = ProblemDetail.forStatusAndDetail(
            HttpStatus.UNPROCESSABLE_ENTITY, e.getMessage());
    pd.setType(java.net.URI.create("https://api.nbi.in/problems/insufficient-funds"));
    pd.setTitle("Insufficient Funds");
    pd.setProperty("traceId", MDC.get("traceId"));
    return pd; // Content-Type: application/problem+json automatically
}

// Wrong: try-catch in each controller, stack trace leaked, no trace id.
@PostMapping("/transfers")
public ResponseEntity<?> create(@RequestBody TransferRequest req) {
    try {
        return ResponseEntity.ok(transferService.create(req));
    } catch (Exception e) {
        return ResponseEntity.status(500)
                .body(Map.of("error", e.toString())); // Stack trace leaked!
    }
}

// Correct: let exceptions bubble up to centralised @RestControllerAdvice.
@PostMapping("/transfers")
public ResponseEntity<TransferResponse> create(
        @Valid @RequestBody TransferRequest req) {
    TransferResponse resp = transferService.create(req);
    return ResponseEntity.created(java.net.URI.create("/api/v1/transfers/" + resp.id()))
            .body(resp);
    // Exceptions are caught by GlobalExceptionHandler automatically.
}