Spring Boot services · Chapter 13 of 41
Handling errors
By the end of this chapter you can turn exceptions into status codes that tell the truth, with one error format every client can read. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: REST APIs
- 5 tasks
- Spring Boot
- In the all labs plan
The first 2 chapters of Spring Boot services are free. This one comes with the all labs plan.
Why you need this
The Tapri app team sends Kabir their complaints about Tapri Cloud's errors. A missing order is a server error:
$ curl -i localhost:8081/orders/42
HTTP/1.1 500
Content-Type: application/json
Transfer-Encoding: chunked
Date: Wed, 07 Oct 2026 10:13:52 GMT
Connection: close
{"timestamp":"2026-10-07T10:13:52.597Z","status":500,"error":"Internal Server Error","path":"/orders/42"}
Paying an order a second time answers 200 again, so the app charges the customer twice. A form with two mistakes says only "title":"Bad Request", not which fields. And Ravi's status endpoint says everything is fine:
$ curl -i localhost:8081/orders/42/status
HTTP/1.1 200
Content-Type: application/json
Transfer-Encoding: chunked
Date: Wed, 07 Oct 2026 10:13:52 GMT
{"error":"order not found"}
The app showed a green tick for an order that does not exist. Fixing this with a try in every controller method means each one invents its own error format, and the next method forgets.
What you build: 5 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
ApiExceptionHandler.java: answer a missing order with 404 problem JSON
Add a handler to ApiExceptionHandler for OrderNotFoundException that answers 404 Not Found as problem JSON (Content-Type application/problem+json): status 404, title "Order not found", detail the exception's message ("No order 4242"), and a property orderId with the id as a number (4242).
An order that exists still answers 200 with its JSON from GET /orders/{id}.
- Task 2
OrderService.java: refuse to take payment twice with 409 Conflict
Make OrderService.pay(id) throw OrderAlreadyPaidException when the order is already paid. The first payment still answers 200 with the order and "paid": true.
Then add a handler to ApiExceptionHandler that answers the second payment with 409 Conflict as problem JSON: status 409 and title "Order already paid".
- Task 3
ApiExceptionHandler.java: list every field error in a 400
When a POST /orders body fails validation, answer 400 Bad Request as problem JSON with title "Invalid order" and a property errors: a JSON object with one entry per field that failed, its name mapped to its message, such as {"customerName": "is required", "quantity": "must be at least 1"}. If a field breaks two rules, keep one message.
A field that is fine is not in errors: quantity 30 with a good name gives only "quantity": "must be at most 20". A valid order (Anjali, 3) still answers 201. Override handleMethodArgumentNotValid; an exception handler for MethodArgumentNotValidException stops the app starting.
- Task 4
ApiExceptionHandler.java: a 500 that hides the details
Answer every other exception (the broken printer behind GET /orders/{id}/receipt) with 500 Internal Server Error as problem JSON: title "Internal error" and detail exactly "Something went wrong. We are looking into it." No part of the exception's message (10.0.4.7, tapri-print) may appear in the body; log the exception instead.
Spring's own errors keep their status: a path with no handler (GET /no/such/page) still answers 404, and DELETE /orders/{id} still answers 405.
- Task 5 · interview question
Interview: stop GET /orders/{id}/status answering 200 with an error message
Make GET /orders/{id}/status answer 404 Not Found as problem JSON for an order that does not exist (987654), with the orderId property from task 1 and no "error" field. An order that exists still answers 200 with {"id": ..., "status": "UNPAID"} (PAID once paid).
This needs task 1's handler. Be ready to explain why a 200 with an error message is wrong.
What you will learn
- @RestControllerAdvice and @ExceptionHandler: one class that turns exceptions from every controller into answers.
- ProblemDetail: the standard error body (RFC 9457).
- ResponseEntityExceptionHandler: Spring's own errors (404, 405, bad input) in the same format, and how to change one.
- Honest status codes: why an error must never answer 200.
More in REST APIs
Build "Handling errors" yourself
Tapri Cloud: the counters’ Java grows into a Spring Boot service with a database. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Spring Boot services are free. This one comes with the all labs plan.