Spring Boot HTTP Status Codes: Which to Return and How

// 1xx — Informational: request received, processing continues
// 2xx — Success: request was received, understood, and accepted
// 3xx — Redirection: further action needed to complete the request
// 4xx — Client Error: request contains bad syntax or cannot be fulfilled
// 5xx — Server Error: server failed to fulfil a valid request

// ── Retry guidance ────────────────────────────────────────────────────
// 2xx — success, no retry needed
// 3xx — follow the redirect (Location header)
// 4xx — do NOT retry unchanged (client must fix the request first)
//       exceptions: 408 Request Timeout, 429 Too Many Requests (after Retry-After)
// 5xx — may retry with backoff, if the request is idempotent
// 503 — retry after the Retry-After interval, if present

// ── Cacheable by default (heuristic caching, GET/HEAD) ────────────────
// 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, 501
// Not cacheable by default: 201, 202, 302, 307, most other 4xx/5xx

// ── 200 OK ────────────────────────────────────────────────────────────
// The standard success response. Use for GET, and for PUT/PATCH when
// the response includes a body.
@GetMapping("/{id}")
public ResponseEntity<UserResponse> findById(@PathVariable Long id) {
    return userService.findOptionalById(id)
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.notFound().build());   // never return null for "not found"
}

// ── 201 Created ───────────────────────────────────────────────────────
// Resource was created. Include a Location header pointing to the new
// resource. A body is optional but recommended.
@PostMapping
public ResponseEntity<UserResponse> create(
        @RequestBody @Valid CreateUserRequest request,
        UriComponentsBuilder uriBuilder) {
    UserResponse created = userService.create(request);
    URI location = uriBuilder.path("/users/{id}")
        .buildAndExpand(created.id()).toUri();
    return ResponseEntity.created(location).body(created);
}

// ── 202 Accepted ──────────────────────────────────────────────────────
// Request accepted for processing but not yet complete (async).
// Give the client a way to check progress: a status URL in Location or the body.
@PostMapping("/{id}/export")
public ResponseEntity<ExportStatusResponse> startExport(@PathVariable Long id) {
    String jobId = exportService.startAsync(id);
    URI statusUri = URI.create("/jobs/" + jobId);
    return ResponseEntity.accepted()
        .location(statusUri)
        .body(new ExportStatusResponse(jobId, "PENDING"));
}

// ── 204 No Content ────────────────────────────────────────────────────
// Success with no response body. Standard for DELETE and for PUT/PATCH
// when you choose not to return the updated resource.
// A 204 response must not contain a body.
@DeleteMapping("/{id}")
public ResponseEntity<Void> delete(@PathVariable Long id) {
    userService.delete(id);
    return ResponseEntity.noContent().build();
}

// ── 206 Partial Content ───────────────────────────────────────────────
// Returned for Range requests (video streaming, resumable downloads).
// Spring MVC handles the Range header when the body is a Resource and
// turns the response into 206 with Content-Range automatically.
@GetMapping("/videos/{id}")
public ResponseEntity<Resource> streamVideo(@PathVariable Long id) {
    Resource video = videoService.load(id);
    return ResponseEntity.ok()
        .header(HttpHeaders.ACCEPT_RANGES, "bytes")
        .contentType(MediaType.parseMediaType("video/mp4"))
        .body(video);
    // Request:  Range: bytes=0-1023
    // Response: 206 Partial Content, Content-Range: bytes 0-1023/50000
}

// ── 301 Moved Permanently / 308 Permanent Redirect ───────────────────
// Resource has a new permanent URI. Clients and search engines should
// update their links. Browsers cache this very aggressively.
// Use 308 instead of 301 when the HTTP method must be preserved.
@GetMapping("/users/{id}")
public ResponseEntity<Void> redirectOldPath(@PathVariable Long id) {
    URI newUri = URI.create("/api/v2/users/" + id);
    return ResponseEntity.status(HttpStatus.MOVED_PERMANENTLY)
        .location(newUri)
        .build();
}

// ── 302 Found / 307 Temporary Redirect / 303 See Other ───────────────
// Temporary redirect: keep using the original URI for future requests.
// Used in login and OAuth flows. 307 preserves the method, 303 forces GET.
@GetMapping("/login/start")
public ResponseEntity<Void> startLogin() {
    return ResponseEntity.status(HttpStatus.FOUND)
        .location(URI.create("https://idp.example.com/authorize"))
        .build();
}

// ── 304 Not Modified ──────────────────────────────────────────────────
// Client's cached version is still valid — no body returned.
// Used with ETag / If-None-Match and Last-Modified / If-Modified-Since.
@GetMapping("/{id}")
public ResponseEntity<UserResponse> findById(
        @PathVariable Long id,
        @RequestHeader(value = "If-None-Match", required = false) String ifNoneMatch) {

    UserResponse user = userService.findById(id);
    String etag = "\"" + user.version() + "\"";    // ETags are quoted strings

    if (etag.equals(ifNoneMatch)) {
        return ResponseEntity.status(HttpStatus.NOT_MODIFIED)
            .eTag(etag).build();         // 304 — client cache is current
    }
    return ResponseEntity.ok().eTag(etag).body(user);  // 200 + fresh body
}

// ── Simpler: let Spring handle the comparison ─────────────────────────
@GetMapping("/v2/{id}")
public ResponseEntity<UserResponse> findByIdV2(@PathVariable Long id, WebRequest request) {
    UserResponse user = userService.findById(id);
    String etag = "\"" + user.version() + "\"";
    if (request.checkNotModified(etag)) {
        return null;      // Spring has already set 304 and the headers
    }
    return ResponseEntity.ok().eTag(etag).body(user);
}

// ── 400 Bad Request ──────────────────────────────────────────────────
// Malformed JSON, type mismatch, or failed Bean Validation.
// Most common 4xx — return field-level detail when possible.
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidation(
        MethodArgumentNotValidException ex) {
    Map<String, String> errors = ex.getBindingResult().getFieldErrors()
        .stream().collect(Collectors.toMap(
            FieldError::getField,
            fe -> fe.getDefaultMessage() != null ? fe.getDefaultMessage() : "Invalid",
            (a, b) -> a));
    return ResponseEntity.badRequest()
        .body(new ErrorResponse(400, "Validation Failed", errors));
}
// Related Spring exceptions that also map to 400:
//   HttpMessageNotReadableException   (invalid JSON body)
//   MethodArgumentTypeMismatchException (e.g. /users/abc for a Long id)
//   MissingServletRequestParameterException
//   HandlerMethodValidationException  (Spring 6.1+: validation of @RequestParam/@PathVariable)

// ── 401 Unauthorized ─────────────────────────────────────────────────
// Authentication is required and has not been provided or is invalid.
// (Misleadingly named — it means "unauthenticated", not "unauthorized".)
// Spring Security returns this automatically; the response must include a
// WWW-Authenticate header, which Spring Security's entry points add.

// ── 403 Forbidden ────────────────────────────────────────────────────
// Authenticated but not authorised to perform this action.
// Spring Security returns this automatically for access denied.
// Use 404 instead if revealing the resource's existence is sensitive.

// ── 404 Not Found ────────────────────────────────────────────────────
// Resource does not exist.
@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(UserNotFoundException ex) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND)
        .body(ErrorResponse.of(404, "Not Found", ex.getMessage()));
}

// ── 405 Method Not Allowed ────────────────────────────────────────────
// HTTP method not supported for this URI.
// Spring MVC returns this automatically, with an Allow header.

// ── 409 Conflict ─────────────────────────────────────────────────────
// State conflict — duplicate email, optimistic lock failure,
// or business rule violation.
@ExceptionHandler(EmailAlreadyExistsException.class)
public ResponseEntity<ErrorResponse> handleConflict(EmailAlreadyExistsException ex) {
    return ResponseEntity.status(HttpStatus.CONFLICT)
        .body(ErrorResponse.of(409, "Conflict", ex.getMessage()));
}

// ── 410 Gone ────────────────────────────────────────────────────────
// Resource existed but was permanently deleted.
// Stronger signal than 404 — tells clients to remove their links.

// ── 412 Precondition Failed ──────────────────────────────────────────
// If-Match / If-Unmodified-Since did not match the current state.
// Typical for optimistic locking with ETags on PUT/PATCH/DELETE.

// ── 415 Unsupported Media Type ────────────────────────────────────────
// Content-Type of the request body is not supported.
// Spring MVC returns this automatically when 'consumes' does not match.

// ── 422 Unprocessable Content (Entity) ────────────────────────────────
// Request is syntactically valid but semantically invalid.
// Some APIs prefer this over 400 for domain-level validation failures.
@ExceptionHandler(DomainValidationException.class)
public ResponseEntity<ErrorResponse> handleDomainValidation(
        DomainValidationException ex) {
    return ResponseEntity.status(HttpStatus.UNPROCESSABLE_ENTITY)
        .body(ErrorResponse.of(422, "Unprocessable Entity", ex.getMessage()));
}

// ── 429 Too Many Requests ─────────────────────────────────────────────
// Rate limit exceeded. Always include a Retry-After header.
@ExceptionHandler(RateLimitExceededException.class)
public ResponseEntity<ErrorResponse> handleRateLimit(RateLimitExceededException ex) {
    return ResponseEntity.status(HttpStatus.TOO_MANY_REQUESTS)
        .header(HttpHeaders.RETRY_AFTER, String.valueOf(ex.getRetryAfterSeconds()))
        .body(ErrorResponse.of(429, "Too Many Requests", "Rate limit exceeded"));
}

@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // ── 500 Internal Server Error ─────────────────────────────────────
    // Catch-all for unhandled server-side failures.
    // Log the full stack trace server-side; return a generic message to the client
    // — never expose internal details (stack traces, SQL errors, file paths).
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleAll(Exception ex) {
        log.error("Unhandled exception", ex);   // full detail in logs
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(ErrorResponse.of(500, "Internal Server Error",
                "An unexpected error occurred"));   // generic to client
    }

    // ── 502 Bad Gateway ───────────────────────────────────────────────
    // This server received an invalid response from an upstream service.
    // Return when a downstream dependency (another microservice, third-party API)
    // returns an unexpected response.
    @ExceptionHandler(UpstreamServiceException.class)
    public ResponseEntity<ErrorResponse> handleUpstream(UpstreamServiceException ex) {
        return ResponseEntity.status(HttpStatus.BAD_GATEWAY)
            .body(ErrorResponse.of(502, "Bad Gateway",
                "Upstream service returned an invalid response"));
    }

    // ── 503 Service Unavailable ───────────────────────────────────────
    // Server is temporarily unable to handle the request — overloaded,
    // in maintenance, or a critical dependency is down.
    // Include a Retry-After header when the recovery time is known.
    @ExceptionHandler(ServiceUnavailableException.class)
    public ResponseEntity<ErrorResponse> handleUnavailable(ServiceUnavailableException ex) {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
            .header(HttpHeaders.RETRY_AFTER, "30")
            .body(ErrorResponse.of(503, "Service Unavailable",
                "The service is temporarily unavailable"));
    }

    // ── 504 Gateway Timeout ───────────────────────────────────────────
    // This server did not receive a timely response from an upstream service.
    @ExceptionHandler(UpstreamTimeoutException.class)
    public ResponseEntity<ErrorResponse> handleTimeout(UpstreamTimeoutException ex) {
        return ResponseEntity.status(HttpStatus.GATEWAY_TIMEOUT)
            .body(ErrorResponse.of(504, "Gateway Timeout",
                "Upstream service timed out"));
    }
}

// Safer alternative for the catch-all: extend ResponseEntityExceptionHandler,
// which already returns the correct 4xx codes for Spring MVC's own exceptions:
//
// @RestControllerAdvice
// public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
//     @ExceptionHandler(Exception.class) ...   // only reached for truly unexpected errors
// }

// application.properties
// spring.mvc.problemdetails.enabled=true

@RestControllerAdvice
public class ProblemExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ProblemDetail handleNotFound(UserNotFoundException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.NOT_FOUND, ex.getMessage());
        problem.setTitle("User not found");
        problem.setType(URI.create("https://api.example.com/problems/user-not-found"));
        problem.setProperty("userId", ex.getUserId());     // custom field
        return problem;
    }

    @ExceptionHandler(EmailAlreadyExistsException.class)
    public ProblemDetail handleConflict(EmailAlreadyExistsException ex) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.CONFLICT, ex.getMessage());
        problem.setTitle("Email already registered");
        return problem;
    }
}

// Response:
// HTTP/1.1 404 Not Found
// Content-Type: application/problem+json
// {
//   "type": "https://api.example.com/problems/user-not-found",
//   "title": "User not found",
//   "status": 404,
//   "detail": "User not found: 42",
//   "instance": "/users/42",
//   "userId": 42
// }

// ── HttpStatus enum — the most common constants ───────────────────────
HttpStatus.OK                        // 200
HttpStatus.CREATED                   // 201
HttpStatus.ACCEPTED                  // 202
HttpStatus.NO_CONTENT                // 204
HttpStatus.PARTIAL_CONTENT           // 206
HttpStatus.MOVED_PERMANENTLY         // 301
HttpStatus.FOUND                     // 302
HttpStatus.NOT_MODIFIED              // 304
HttpStatus.TEMPORARY_REDIRECT        // 307
HttpStatus.PERMANENT_REDIRECT        // 308
HttpStatus.BAD_REQUEST               // 400
HttpStatus.UNAUTHORIZED              // 401
HttpStatus.FORBIDDEN                 // 403
HttpStatus.NOT_FOUND                 // 404
HttpStatus.METHOD_NOT_ALLOWED        // 405
HttpStatus.CONFLICT                  // 409
HttpStatus.GONE                      // 410
HttpStatus.PRECONDITION_FAILED       // 412
HttpStatus.UNSUPPORTED_MEDIA_TYPE    // 415
HttpStatus.UNPROCESSABLE_ENTITY      // 422 (newer Spring versions also offer a "content" name; check yours)
HttpStatus.TOO_MANY_REQUESTS         // 429
HttpStatus.INTERNAL_SERVER_ERROR     // 500
HttpStatus.BAD_GATEWAY               // 502
HttpStatus.SERVICE_UNAVAILABLE       // 503
HttpStatus.GATEWAY_TIMEOUT           // 504

// ── HttpStatus utility methods ────────────────────────────────────────
HttpStatus notFound = HttpStatus.valueOf(404);        // throws for unknown codes
HttpStatus unknown  = HttpStatus.resolve(999);        // null if unknown code
HttpStatusCode any  = HttpStatusCode.valueOf(299);    // works for non-standard codes too
notFound.value()                                      // int: 404
notFound.getReasonPhrase()                            // "Not Found"
notFound.is2xxSuccessful()                            // false
notFound.is4xxClientError()                           // true
notFound.is5xxServerError()                           // false
notFound.isError()                                    // true (4xx or 5xx)

// ── @ResponseStatus on exception classes ──────────────────────────────
// Annotate a custom exception to map it to a status code automatically:
@ResponseStatus(HttpStatus.NOT_FOUND)
public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(Long id) {
        super("User not found: " + id);
    }
}
// Any unhandled UserNotFoundException → 404 Not Found
// (Without a @RestControllerAdvice handler — less control over body shape)

// ── ResponseStatusException — no custom exception class needed ─────────
@GetMapping("/{id}")
public UserResponse findById(@PathVariable Long id) {
    return userService.findOptionalById(id)
        .orElseThrow(() -> new ResponseStatusException(
            HttpStatus.NOT_FOUND, "User not found: " + id));
}

// ── @ResponseStatus on controller methods ─────────────────────────────
// Forces a specific status on a method that returns void or a plain object:
@PostMapping
@ResponseStatus(HttpStatus.CREATED)    // 201 Created — no ResponseEntity needed
public UserResponse create(@RequestBody @Valid CreateUserRequest request) {
    return userService.create(request);
    // Returns 201 + serialized body — but no Location header control
}

// Prefer ResponseEntity for creation — it allows the Location header.
// @ResponseStatus is convenient for simple cases where headers don't matter.

// ── GET requests ─────────────────────────────────────────────────────
// Resource found and returned          → 200 OK
// Resource not found                   → 404 Not Found
// Cached response still valid          → 304 Not Modified
// Access denied                        → 403 Forbidden (or 404 to hide existence)

// ── POST requests (create) ────────────────────────────────────────────
// Resource created                     → 201 Created + Location header
// Request accepted, processing async   → 202 Accepted + status URL
// Validation failed                    → 400 Bad Request + field errors
// Duplicate / conflict                 → 409 Conflict
// Business rule violation              → 422 Unprocessable Content

// ── PUT requests (full update) ────────────────────────────────────────
// Resource updated, body returned      → 200 OK
// Resource updated, no body            → 204 No Content
// Resource created by PUT              → 201 Created
// Resource not found                   → 404 Not Found
// Optimistic lock conflict             → 409 Conflict (or 412 with If-Match)

// ── PATCH requests (partial update) ──────────────────────────────────
// Fields updated, body returned        → 200 OK
// Fields updated, no body              → 204 No Content
// Resource not found                   → 404 Not Found
// Invalid field value                  → 400 Bad Request

// ── DELETE requests ───────────────────────────────────────────────────
// Resource deleted                     → 204 No Content
// Resource not found                   → 404 Not Found (or 204 — be consistent)
// Resource permanently gone            → 410 Gone

// ── Auth scenarios ────────────────────────────────────────────────────
// No credentials provided              → 401 Unauthorized
// Invalid credentials                  → 401 Unauthorized
// Valid credentials, wrong permissions → 403 Forbidden
// Rate limit exceeded                  → 429 Too Many Requests

// ── Server scenarios ──────────────────────────────────────────────────
// Unhandled exception                  → 500 Internal Server Error
// Upstream service error               → 502 Bad Gateway
// Server overloaded / maintenance      → 503 Service Unavailable
// Upstream timeout                     → 504 Gateway Timeout

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean UserService userService;   // @MockBean on older Spring Boot versions

    @Test
    void createReturns201WithLocation() throws Exception {
        when(userService.create(any())).thenReturn(new UserResponse(42L, "Ana"));

        mvc.perform(post("/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{\"name\":\"Ana\",\"email\":\"ana@example.com\"}"))
            .andExpect(status().isCreated())
            .andExpect(header().string("Location", endsWith("/users/42")))
            .andExpect(jsonPath("$.id").value(42));
    }

    @Test
    void unknownUserReturns404() throws Exception {
        when(userService.findOptionalById(99L)).thenReturn(Optional.empty());

        mvc.perform(get("/users/99"))
            .andExpect(status().isNotFound());
    }

    @Test
    void invalidBodyReturns400() throws Exception {
        mvc.perform(post("/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content("{}"))
            .andExpect(status().isBadRequest());
    }

    @Test
    void deleteReturns204WithoutBody() throws Exception {
        mvc.perform(delete("/users/42"))
            .andExpect(status().isNoContent())
            .andExpect(content().string(""));
    }
}