ResponseEntity vs @ResponseStatus — Dynamic vs Static Status Codes

Direct Answer

ResponseEntity is a return value containing status, headers, and an optional body, so a method can construct different responses at runtime. @ResponseStatus is runtime metadata that assigns a fixed status (and optional reason) to a handler method or exception type. It is not a compile-time mechanism. For centralized APIs, exception handlers often give more control than annotating exception classes.

Code Example

// @ResponseStatus — FIXED status, declared at compile time
@ResponseStatus(HttpStatus.CREATED) // always 201
@PostMapping("/users")
public User create(@RequestBody User user) {
    return userService.save(user);
}

// ResponseEntity — DYNAMIC status decided at runtime
@GetMapping("/users/{id}")
public ResponseEntity<User> getUser(@PathVariable Long id) {
    return userService.findById(id)
        .map(ResponseEntity::ok)                     // 200 + body
        .orElse(ResponseEntity.notFound().build());  // 404
}

Use @ResponseStatus when the code never changes; ResponseEntity when status, headers, or body vary per request.

Common Mistakes & Pitfalls

• Overusing ResponseEntity for Fixed Status: Freshers wrap every response in ResponseEntity even when the status never changes. A method that always returns 204 doesn't need ResponseEntity.noContent().build()—just annotate with @ResponseStatus(NO_CONTENT) and return void. Simpler code, same result.
• Forgetting @ResponseStatus on Custom Exceptions: You create ResourceNotFoundException but don't annotate it, so Spring returns 500 Internal Server Error instead of 404. The annotation tells Spring what status to send when that exception bubbles up.
• Mixing Both on Same Method: Putting @ResponseStatus(CREATED) on a method that returns ResponseEntity.ok(...) creates confusion—the ResponseEntity status wins, but the annotation misleads readers.