Validation and Error Handling

An API is judged by its failure responses far more than by its success responses. The happy path is easy: it was written first, tested first, demonstrated first. Errors, on the other hand, show up in production, at a customer you don't know, in a situation nobody anticipated — and that is when the quality of the API is revealed.

The classic symptom is a catalog of inconsistencies. A nonexistent identifier returns 500 with a Spring HTML error page. A missing required field returns 400 with an unreadable default Spring structure. A business conflict returns 200 with {"succes": false}. One developer in a hurry adds try/catch in a controller, another adds @ResponseStatus on an exception, a third returns a Map. Six months later, the client team has written different code for every endpoint, and nobody dares change anything anymore.

The way out of this dead end comes down to two decisions. First, validate inputs at the edge of the application, declaratively, so that no questionable data ever reaches the service. Second, centralize the translation of exceptions into HTTP responses in a single place, with a single format. Spring 6 provides that format: ProblemDetail, the implementation of RFC 9457.