We have been leaving TODO labels behind for four lessons. The 404s are built by hand in every controller with ResponseEntity.notFound(). The business rules from 03-03 throw IllegalStateExceptions that turn into server errors with the stack trace inside. The ConstraintViolationException from 03-04 comes out as a 500 when the fault lies with the client. And validation errors respond "Invalid request content." without saying which field failed. All of that is settled in this lesson. We will build CicloUrbana's exception hierarchy, centralise it in a single global handler, adopt the standard RFC 7807 Problem Details format that Spring Boot 3 supports natively, and make sure no error leaks information that must not leave the server.

1. Spring Boot's default behaviour
2. Why it is not enough for a public API
3. CicloUrbana's exception hierarchy
4. @ResponseStatus on the exception and its limits
5. @ExceptionHandler local to the controller
6. @RestControllerAdvice: the global handler
7. RFC 7807: Problem Details
8. Validation errors with the list of fields
9. Framework exceptions
10. Not leaking sensitive information
11. What to log according to severity
12. A trace identifier in the response
13. Common Mistakes and Tips
14. Exercises

Spring Boot never leaves an exception without a response. When one escapes the controller, the DispatcherServlet —whose journey we sketched in 03-01— passes it through a chain of HandlerExceptionResolvers. If none recognises it, the request is internally forwarded to /error, served by the BasicErrorController. If you add a test endpoint that throws IllegalStateException, the response is this:

That format is controlled by four properties:

With include-message and include-stacktrace set to always, the response goes on to include the full message and the entire stack trace: package names, library versions, line numbers. That is gold for anyone hunting for vulnerabilities. include-stacktrace must be never in production, no exceptions.

Even if we tune those properties, the default handling has four problems that configuration cannot fix. Everything is a 500: IllegalStateException, IllegalArgumentException and NoSuchElementException all come out the same, even though some are the client's fault and others ours, and that ruins monitoring —module 9's alerting system will wake somebody at dawn over a 404. The client cannot program against the error, because there is no stable code to branch on, only an English string that can change in any release. There is no useful context: "Bad Request" does not say which field was wrong. And the format is not a standard, so every client writes its own parser.

What a public API needs is for each kind of failure to have a correct HTTP code, a stable identifier, a useful message and a uniform format. That is what we are going to build.

Every domain exception inherits from a common base, in com.ciclourbana.common.exceptions:

The code field is what makes the API programmable: the client reacts to STATION_FULL without depending on the message text, which can be translated or rewritten without breaking anything. The concrete exceptions:

The complete mapping to HTTP codes:

With this, the services stop throwing IllegalStateException:

Notice the orElseThrow pattern: it turns an empty Optional into the right exception in a single expression, and it is the reason repositories return Optional and not null.

The quickest way to associate an HTTP code with an exception is to annotate it with @ResponseStatus(HttpStatus.NOT_FOUND). Spring detects it with ResponseStatusExceptionResolver and responds 404. It works, it is one line, and it has three serious limits:

For those reasons, CicloUrbana does not use @ResponseStatus on its exceptions: the complete mapping lives in the global handler, in a single place that can be read at a glance.

There is an interesting variant, ResponseStatusException, which carries the status inside: throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Station not found"). It is handy for prototypes, but it couples the service layer to the web API —HttpStatus is a Spring Web class— and it does not allow the code field. The course mentions it and does not adopt it.

A method annotated with @ExceptionHandler inside a controller catches the exceptions of that controller:

Its limited scope is both its virtue and its flaw: it works for an exception specific to one particular controller, but repeating it in every class multiplies the code, so CicloUrbana uses the global handler and reserves the local ones for genuinely particular cases. A precedence fact worth remembering: the local handler always beats the global one when both catch the same exception.

@RestControllerAdvice is @ControllerAdvice + @ResponseBody: a class whose @ExceptionHandlers apply to all the controllers.

Three important details. Returning ProblemDetail directly is enough: Spring recognises it, sets the status from the status field and adds Content-Type: application/problem+json, with no need for a ResponseEntity. The Exception handler does not leak e.getMessage(): the real message goes to the log and only a generic text with a trace identifier reaches the client (section 10). And resolution order is by type specificity, not by declaration order: if a StationFullException is thrown, Spring picks the ResourceConflictException handler —its nearest superclass with a handler— and not the Exception one, which is why the latter can be declared without fear of it swallowing the rest.

When there are several @RestControllerAdvices —for example, one for the domain and another contributed by Spring Security in module 5—, the tie-break does depend on order, and it is controlled with @Order: @Order(Ordered.HIGHEST_PRECEDENCE) on the security handler and @Order(Ordered.LOWEST_PRECEDENCE) on the general one, which acts as a safety net. @RestControllerAdvice also accepts basePackages, assignableTypes or annotations to limit its scope, useful when a public API and an internal panel with different error formats coexist.

With the handler in place, the controllers get simpler. The getById from 03-02 loses its ResponseEntity and its .map(...).orElseGet(...):

The TODO we left there is settled: the error path no longer takes up room on the happy path.

RFC 7807 —updated by RFC 9457— defines a standard format for HTTP errors, and Spring Boot 3 supports it natively with the ProblemDetail class. The standard's fields:

The distinction between title and detail is the most confused one: title is fixed for the problem type ("Resource not found") and detail changes with every occurrence ("No station found with identifier 999"). A client can group errors by type and show detail to the user.

The response our handler produces for GET /api/v1/stations/999 is a 404 with Content-Type: application/problem+json and this body:

Content-Type: application/problem+json is set by Spring on its own when it detects a ProblemDetail. It is the MIME type we announced in the table in 03-01.

Spring Boot also offers a global switch that requires writing no handlers at all:

It makes the framework's own exceptions —MethodArgumentNotValidException, HttpRequestMethodNotSupportedException, NoResourceFoundException— produce Problem Details instead of the BasicErrorController format. It does not cover your own, for which the handler is still needed, but it brings coherence to the errors you do not handle explicitly.

There are also ErrorResponseException, a Spring exception that already carries a ProblemDetail inside and lets you throw a fully formed error from anywhere, and ResponseEntityExceptionHandler, a base class with pre-written handlers for every Spring MVC exception that you can extend and override method by method: it gives more coverage out of the box in exchange for less control.

We pick up the debt from 03-04: a MethodArgumentNotValidException contains a BindingResult with every field that failed, and we have to extract them and put them in the response.

The result, with the same request that in 03-04 returned "Invalid request content.":

Now Ribalta's panel can highlight the two fields and show their messages next to each one. Note that name accumulates two errors: grouping into a List<String> loses none, whereas a Map<String, String> would have silently discarded one. And this also settles the 500 trap from 03-04: ConstraintViolationException now responds 400.

Besides our own, we have to handle the ones Spring throws when the request is malformed:

NoResourceFoundException (with spring.mvc.throw-exception-if-no-handler-found: true) and HttpRequestMethodNotSupportedException follow the same pattern; exercise 3 completes the latter with the Allow header. Now that request from the 03-02 .http file which returned an incomprehensible 400 gives something useful for ?minimumCapacity=lots:

An error handler is an attack surface: every piece of data it returns is a piece of data someone can use against you. What must never go out:

The first three almost always arrive by the same route: returning e.getMessage() of an exception you do not control. With ProblemDetail.forStatusAndDetail(INTERNAL_SERVER_ERROR, e.getMessage()) and a database failure, the API responds with something like "could not execute statement; SQL [insert into stations ...]; constraint [uk_stations_name]", which reveals the whole schema. The Exception handler from section 6 does the right thing: a generic message on the way out, the full detail in the log, and a trace identifier joining the two.

The rule: the message of your own exceptions may go out, because we wrote it with the client in mind; the message of someone else's, never.

A subtle case: resource enumeration. If GET /api/v1/users/1 responds 404 and GET /api/v1/users/2 responds 403, an attacker deduces that user 2 exists; for sensitive resources the right answer is 404 in both cases. It does not apply to the Ribalta stations, which are public information, but it does apply to users, and we will return to it in module 5.

Logging everything with log.error renders the log useless: when everything is an error, nothing is.

Two practical rules. Stack traces only at ERROR: a 404 with twenty lines of trace multiplies the log size while adding nothing. And log the exception as the last argument, not concatenated:

SLF4J treats a trailing Throwable argument specially and prints the full stack trace, chained causes included; concatenating loses exactly the information needed to diagnose. Logging in depth arrives in 09-05.

When a Ribalta operator calls saying "I got an error when finishing the rental", the question is which of the hundreds of errors in the log is theirs. The trace identifier answers that: a unique value that appears at the same time in the client's response and in the log line. The homespun version is the one we already have: a UUID.randomUUID() in the Exception handler. It only covers errors and does not relate the log lines of a single request to each other. The good version uses SLF4J's MDC (Mapped Diagnostic Context), which attaches data to the current thread and makes every log line of a request carry the same identifier:

That MDC.remove in the finally is not optional: without it, a request that fails leaves its identifier stuck to the thread and the next request served by that thread writes a trace in the log that does not belong to it. It is a hard error to diagnose precisely because it corrupts the diagnostic tool itself.

It is included in the log pattern with %X{traceId:-no-trace} —%X reads the MDC and :-no-trace is the default value—, and in the handler problem.setProperty("trace", MDC.get(TraceFilter.MDC_KEY)) is all it takes:

The result, in the server log and in the response the operator receives:

With a3f5c9e1 you locate in the log the exact request and all its lines. This identifier is the seed of the distributed tracing of 09-06, where the trace will stay alive across several services.

Leaving include-stacktrace: always in production. It is the most common information leak in Spring Boot applications. It must be never.

Catching Exception in the controller with a try/catch. It bypasses the global handler and scatters error logic. Let the exception rise.

Returning e.getMessage() of somebody else's exception. It is the route through which database schemas and system paths escape.

Logging everything with log.error. A 404 is not a server error. When everything is ERROR, alerts stop meaning anything.

Forgetting MDC.remove(). The trace leaks into the next request on the same thread and corrupts the log exactly when you need it most.

Using @ResponseStatus and the global handler at the same time. Having the mapping in two places ends in inconsistencies; the course chooses the handler. And using Map<String, String> for validation errors silently loses the additional errors of a single field: use Map<String, List<String>>.

Tip: write the exception-to-HTTP-code table first, since it is the handler's specification, and test every error branch by adding one request per type to the .http file; in module 6 those requests become integration tests that stop a refactor from breaking the error contract.

StationService.create still throws IllegalStateException when the name is repeated. Create DuplicateStationException, make it respond 409 and add to the response the identifier of the station that already exists, so that Ribalta's panel can link to it directly.

Extend the MethodArgumentNotValidException handler so that each error includes the field name, the message translated according to Accept-Language and the rejected value, with a list of sensitive fields whose value is never returned.

The HttpRequestMethodNotSupportedException handler from section 9 returns the correct 405 but does not include the Allow header, which RFC 9110 requires. Fix it and explain why that case needs ResponseEntity while the others do not.

Solution 1.

Notice the change in the repository: existsByName returned a boolean and now we need findByName, which returns Optional<Station>. It is a recurring pattern: if throwing the error requires data from the conflicting resource, the repository has to return you the object, not a boolean. The specific handler:

The existingLink field is a touch of HATEOAS where it genuinely pays: the panel can offer "view the existing station" without building the URL. And even if there were no handler for DuplicateStationException, the exception would still respond 409 thanks to the one for its superclass ResourceConflictException; the specific handler only adds the two extra fields. That is the advantage of a well-designed hierarchy.

Solution 2.

With Accept-Language: es:

Three decisions worth pointing out. First: Locale as a handler parameter, which Spring injects from the LocaleResolver of 03-04, so that messageSource.getMessage(error, language) resolves {station.name.required} in the right language. Second: the sensitive-field list is a deny list, with the problem we already know —a new field called socialSecurityNumber would not be on it—, so in a system with genuinely sensitive data the right approach is the reverse: return no value at all except those explicitly marked as safe. Third: truncating at 100 characters stops a malicious client from provoking enormous responses.

Solution 3.

For DELETE /api/v1/stations, the response is a 405 with Allow: GET, POST and an application/problem+json body that repeats the methods in allowedMethods.

Why this case needs ResponseEntity. ProblemDetail describes only the body of the response: it has status so that Spring sets the code, but it has no way of expressing headers. RFC 9110 says a 405 must include Allow, so it has to be wrapped. It is exactly the criterion we set in the table in 03-02: ResponseEntity when headers are needed, the object directly when they are not.

It is worth noting the deliberate duplication: the allowed methods appear in the Allow header and in the allowedMethods field. The header is what the standard requires and what intermediaries read; the body field is what most JavaScript clients will read in practice, because reading headers from the browser requires the CORS exposedHeaders configuration we saw in 03-02. Duplicating here costs one line and saves a problem.

Four lessons' worth of debt is settled. You know what Spring Boot does by default —the forward to /error and the BasicErrorController— and why the server.error.include-* properties are not enough for a public API, starting with the fact that everything comes out as a 500. You have built CicloUrbana's exception hierarchy with CicloUrbanaException as its base, its code field that makes the API programmable without depending on the text, and the concrete exceptions of the Ribalta domain, each with its HTTP code in a table that is the handler's specification. You know @ResponseStatus and its three limits, the local @ExceptionHandler and its precedence over the global one, and above all the @RestControllerAdvice that centralises handling in a single class, with the type-specificity resolution that lets you declare an Exception handler without fear of it swallowing the rest.

CicloUrbana's errors now speak the RFC 7807 Problem Details standard, with type, title, status, detail, instance and our own extensions, served with application/problem+json and complemented by spring.mvc.problemdetails.enabled. The validation errors from 03-04 finally return the exact list of offending fields, grouped into a Map<String, List<String>> so none is lost, and ConstraintViolationException no longer comes out as a 500. You handle the framework's exceptions —unreadable JSON, wrong type, method not allowed, non-existent path— and you know none of them must leak e.getMessage(). You have the table of what must never go out in an error, the log-level policy by severity, and a trace identifier propagated with the MDC that appears both in the response and in every log line of that request, with the MDC.remove() in the finally that avoids corrupting the diagnosis.

CicloUrbana now has a complete API: thirteen endpoints, validation at the edge, DTOs that separate the domain from the contract and uniform, well-formed errors. And yet, if tomorrow the Ribalta mobile app team or the council's open data portal team wanted to integrate, they would have to ask us endpoint by endpoint which fields each one accepts, what it returns and which errors it can produce. All that knowledge lives in the code and in our heads, and nowhere else.

Lesson 03-07, Documenting the API with OpenAPI, puts it in writing automatically and in a machine-readable way. We will see what OpenAPI 3.1 is and why a formal contract changes the way teams work together; we will compare code-first and design-first; we will integrate springdoc-openapi with its /v3/api-docs and /swagger-ui.html endpoints; we will document CicloUrbana with @Tag, @Operation, @Parameter, @ApiResponse and @Schema; we will see how the Bean Validation constraints from 03-04 and this lesson's Problem Details appear in the schema on their own; we will group endpoints with GroupedOpenApi; we will export the openapi.json during the build to generate clients; and we will close the module with a review of the API before jumping to real persistence.