There are a hundred HTTP-status cheat sheets. None of them answer the question I actually have mid-controller: "okay, but how do I **return* that in Spring?"* So I built one that does.
▶ Live demo: https://dev48v.github.io/http-status-explorer/
Source (single file, zero deps): https://github.com/dev48v/http-status-explorer
Search by code, name, or meaning; filter by class; click any code to get what it means, when to use it, and a copy-ready Spring Boot snippet.
The distinctions that actually trip people up
401 vs 403. This is the big one:
-
401 Unauthorized→ "I don't know who you are." Missing, expired, or invalid auth. -
403 Forbidden→ "I know exactly who you are — you're just not allowed to do this." Authenticated, but missing the role/scope.
If you're returning 403 for a missing token, that's a bug.
400 vs 422. 400 Bad Request = malformed or fails validation (bad JSON, @Valid failure). 422 Unprocessable Entity = the JSON is fine but it violates a business rule (e.g. "quantity exceeds stock"). Some teams collapse both into 400 — the tool says so.
301/302 vs 307/308. The old redirects (301/302) are allowed to turn your POST into a GET. The newer ones (307/308) preserve the method and body. If you're redirecting a non-GET, you almost always want 307/308.
The "how do I return it in Spring" part
Each code carries the real mechanism. A few examples:
// 201 Created — with a Location header
URI uri = URI.create("/api/orders/" + saved.id());
return ResponseEntity.created(uri).body(saved);
// 204 No Content — successful DELETE
return ResponseEntity.noContent().build();
// 404 — throw, let @RestControllerAdvice map it to a ProblemDetail
orderRepo.findById(id).orElseThrow(() -> new OrderNotFoundException(id));
// 409 Conflict — illegal state transition / duplicate
throw new ResponseStatusException(HttpStatus.CONFLICT, "Order already confirmed");
// 400 — you usually don't write this; @Valid does it for you
public Order create(@Valid @RequestBody CreateOrderRequest req) { … }
The point is to stop guessing between ResponseEntity, @ResponseStatus, ResponseStatusException, and "just let the framework do it" — each code shows the idiomatic choice.
One index.html, no build, works offline. If it becomes your go-to, a star helps others find it: https://github.com/dev48v/http-status-explorer
Top comments (0)