org.springframework.web.server.ResponseStatusException: 404 NOT_FOUND "Produsul 42 nu există"
Este excepția prin care codul tău cere explicit un răspuns cu un anumit status (aici 404) și un motiv. Nu e un bug: Spring o transformă în răspunsul HTTP. Dacă apare unde nu te aștepți, verifică de ce lipsește resursa.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
ResponseStatusException (din Spring 5) îți permite să răspunzi cu orice cod direct din cod, fără clase de excepții proprii: throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Produsul 42 nu există"). Spring o prinde și trimite clientului statusul, iar motivul apare în câmpul message al răspunsului (dacă server.error.include-message=always) sau în detail, dacă folosești ProblemDetail.
Forma din titlu, 404 NOT_FOUND "Produsul 42 nu există", este textul excepției: codul, numele lui și motivul între ghilimele. O vezi în teste (assertThrows), în log (WARN ... Resolved [...ResponseStatusException: 404 NOT_FOUND ...]) sau în clientul care a apelat API-ul.
Greșeala opusă este mai frecventă la început: metoda întoarce null pentru o resursă lipsă, iar clientul primește 200 cu corp gol, ceea ce e mult mai greu de depanat.
De ce apare: cauzele frecvente
1Resursa lipsă întoarsă ca null
@GetMapping("/produse/{id}")
Produs unul(@PathVariable long id) {
return produse.get(id); // null => 200 gol
}Produs p = produse.get(id);
if (p == null) {
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Produsul " + id + " nu există");
}
return p;404 îi spune clientului clar că resursa nu există.
2Status greșit pentru situație
throw new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR, "Produs inexistent");throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Produs inexistent");500 înseamnă eroare a serverului; o resursă lipsă e 404.
Repară eroarea, direct în pagină
GET /produse/42 pentru un produs inexistent răspunde 200 cu corp gol, pentru că metoda întoarce null. Aruncă ResponseStatusException cu 404 și motivul Produsul 42 nu există, ca clientul să primească eroarea corectă.
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.http.*;
import java.util.*;
import org.springframework.web.server.ResponseStatusException;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
record Produs(long id, String nume) {
}
@RestController
class ProdusController {
private final Map<Long, Produs> produse = Map.of(1L, new Produs(1, "Mouse"));
@GetMapping("/produse/{id}")
Produs unul(@PathVariable long id) {
return produse.get(id);
}
}Tomcat started on port 8080 (http)
Started Application
GET /produse/1 → 200
{"id":1,"nume":"Mouse"}
GET /produse/42 → 404
{"status":404,"error":"Not Found","message":"Produsul 42 nu există","path":"/produse/42"}Indiciu
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Produsul " + id + " nu există").
Reparația
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.*;
import org.springframework.stereotype.*;
import org.springframework.beans.factory.annotation.*;
import org.springframework.http.*;
import java.util.*;
import org.springframework.web.server.ResponseStatusException;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
record Produs(long id, String nume) {
}
@RestController
class ProdusController {
private final Map<Long, Produs> produse = Map.of(1L, new Produs(1, "Mouse"));
@GetMapping("/produse/{id}")
Produs unul(@PathVariable long id) {
Produs p = produse.get(id);
if (p == null) {
throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Produsul " + id + " nu există");
}
return p;
}
}De ce merge
Întorcând null, metoda îi spunea clientului „totul e în regulă, dar nu am nimic”: 200 cu corp gol. ResponseStatusException(HttpStatus.NOT_FOUND, ...) transformă lipsa produsului în 404, cu motivul în message. Forma excepției în log și în teste este 404 NOT_FOUND "Produsul 42 nu există". Produsul existent se întoarce în continuare ca JSON.
Alte forme ale mesajului
ResponseStatusException: 400 BAD_REQUEST "Cantitatea trebuie să fie pozitivă"ResponseStatusException: 409 CONFLICT "Comanda a fost deja anulată"
Cum o eviți pe viitor
- Nu întoarce
nulldin controllere pentru resurse lipsă: răspunde 404. - Folosește
ResponseStatusExceptionpentru cazuri punctuale și excepții proprii cu@ResponseStatuspentru cazuri care se repetă. - Scrie motivul pentru client, fără detalii interne (nume de tabele, stive).
- Testează și cererea pentru o resursă inexistentă.
Întrebări frecvente
De ce motivul nu apare în răspuns?
Spring Boot ascunde implicit message. Activează server.error.include-message=always sau folosește ProblemDetail, care pune motivul în detail.
E mai bine decât excepții proprii?
Pentru cazuri izolate, da: e scurt. Când aceeași situație apare în multe locuri, o excepție proprie cu @ResponseStatus e mai ușor de întreținut.
Erori înrudite
java.util.NoSuchElementException: No value present Ai apelat .get() pe un Optional gol, de obicei rezultatul lui findById pentru un id inexistent, iar clientul primește 500. Folosește orElseThrow cu o excepție care dă 404, sau tratează explicit cazul gol. There was an unexpected error (type=Internal Server Error, status=500). Rândul din pagina Whitelabel spune că o excepție netratată a produs 500. Cauza e în log. Pentru excepțiile tale de business, adaugă @ResponseStatus pe clasa excepției sau un @ExceptionHandler, ca să răspunzi cu codul potrivit (404, 409). "message": "No message available" Răspunsul de eroare implicit al Spring Boot nu conține mesajul excepției: de la Boot 2.3, message este ascuns (sau apare ca „No message available” / gol). Activează server.error.include-message=always în dezvoltare sau întoarce mesajul explicit, de exemplu cu ProblemDetail. Învață Spring Boot de la zero, cu exerciții la fiecare lecție
Curs Spring Boot și REST API: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 18 lecții sunt gratuite.
