DEV Community: Vaishnavi Agrawal

Derived Queries or Query Annotations in Spring Data JPA

Vaishnavi Agrawal — Fri, 21 Aug 2026 06:57:50 +0000

Welcome back. The last few pieces about my Purchase Decision API were fairly heavy, from error handling to an AI feature that is allowed to fail to a request that arrived as the wrong method. This one is smaller and more practical: the decision you make every time you add a method to a repository, usually without noticing you made it.

findByEmail feels like magic. findByUserUserIdAndVerdictAndCreatedAtBetweenOrderByScoreDesc feels like a warning.

Both are the same feature. Spring Data JPA reads the name of a method on your repository interface and writes the query for you. You never write the implementation, and for the first few methods it is genuinely delightful.

Then a requirement arrives that the name can technically express. So you express it. Nothing complains, the tests pass, and you have quietly crossed a line nobody marked.

This article is about where that line is, and what it costs to cross it.

What a derived query actually is

It is not magic, and it is not happening at call time. When your application starts, Spring Data parses the method name into a query.

The vocabulary is a real grammar with a finite set of keywords. Subjects like findBy, countBy, existsBy and deleteBy. Predicates like And, Or, Between, LessThan, After, Containing, IgnoreCase. Modifiers like OrderBy, and First or Top for limiting. The full list is in the Spring Data JPA reference, and it is worth reading once, so you know what is there before reaching for something heavier.

Most repositories start out looking like this:

public interface UserRepository extends JpaRepository<User, UUID> {

    Optional<User> findByEmail(String email);

    boolean existsByEmail(String email);
}

Two methods, no implementation, and both read like sentences. This is the style at its best.

The filename problem

A good filename is invoice.pdf. A bad one is invoice-march-2026-final-v2-approved-by-finance-REVISED.pdf. Nobody sat down and decided to write the second one. It grew one qualifier at a time, every single step was reasonable, and the result is a document trying to live inside its own name.

A derived query method name is a filename. It works while the name is genuinely a name. It stops working when the name becomes the content.

My own repository has not reached that point. The longest name in it is this:

List<Decision> findByUserUserIdAndVerdict(UUID userId, Verdict verdict);

That still reads as a sentence. UserUserId looks odd until you know the rule: Spring walks into the user relation and reads its userId field, so nested properties get spelled out by traversal.

Now imagine two more requirements arrive, a date range and a sort order. The name that expresses them is:

List<Decision> findByUserUserIdAndVerdictAndCreatedAtBetweenOrderByScoreDesc(
        UUID userId,
        Verdict verdict,
        LocalDateTime from,
        LocalDateTime to);

Spring is perfectly happy with this. It parses cleanly and returns the right rows. The problem is entirely on the human side: four parameters whose order you work out by re-reading the name, and a name you cannot scan without decoding it.

The name is checked before your app runs

One real advantage of the derived style is easy to miss.

If you name a property the entity does not have, by typo or because someone renamed a field, the application fails at startup. You get a PropertyReferenceException, usually surfacing as "No property found for type". You do not discover it when the endpoint is first called in production. You discover it when the context refuses to start, which Baeldung walks through in detail.

That is a genuinely good property, and a reason to keep using derived methods for everything they handle well.

When the name stops paying for itself

There is no limit in the framework. Spring will parse a name of any length. So this is judgement rather than a rule, and I would rather say so than invent a threshold and present it as official.

Three signals that a method name has stopped earning its place:

You cannot read it aloud in one breath. The name exists so a reader understands the method without opening anything else. If saying it out loud is work, it has stopped doing its job.

You had to count the Ands to get the parameters in the right order. Positional parameters governed by a name is a fine arrangement for two of them. At four it is a puzzle, and puzzles get solved wrongly.

The name encodes something the reader still has to decode. CreatedAtBetween is decodable. A name carrying three conditions, a range and a sort order is a specification in disguise.

The same query, written the other way

@Query moves the query into an annotation and leaves the method name free to say what the method is for:

@Query("""
    select d from Decision d
    where d.user.userId = :userId
      and d.verdict = :verdict
      and d.createdAt between :from and :to
    order by d.score desc
    """)
List<Decision> findDecisionsForUserInRange(
        @Param("userId") UUID userId,
        @Param("verdict") Verdict verdict,
        @Param("from") LocalDateTime from,
        @Param("to") LocalDateTime to);

Longer, and easier to read, which is the trade this whole article is about. The conditions sit on separate lines. The parameters are named rather than positional, so @Param("verdict") tells you what the second argument is without counting anything. And the method name went back to being a name.

You also get what a method name cannot express: joins you control, projections into a DTO, aggregate functions, and anything where the query needs to be shaped rather than merely described.

What you give up is that findByEmail cannot lie to you about what it does, and findDecisionsForUserInRange can, because the name and the query are now two things a future change can pull apart.

The safety myth, and the real gap

One claim about this comparison gets repeated often and is worth correcting.

The claim goes: derived queries are checked at startup so they fail fast, while @Query is just a string and blows up at runtime. It sounds reasonable. It is not true.

JPQL inside @Query is validated at startup as well. During context startup Spring calls EntityManager.createQuery() for each one, and the JPA specification requires that to throw IllegalArgumentException for an invalid query string. A typo in your JPQL breaks the boot. It does not wait politely for the first request. A common way to meet this is writing database column names instead of entity field names, which fails immediately, because JPQL is expressed in terms of your entities rather than your tables.

So the safety difference is not derived versus @Query. Both are JPQL underneath, and both get checked.

The real gap is native queries:

@Query(value = "select * from decisions where user_id = :userId",
       nativeQuery = true)
List<Decision> findByUserNative(@Param("userId") UUID userId);

With nativeQuery = true the string is not parsed as JPQL, so it does not get that startup validation. Your database tells you it is wrong at the moment you run it. That is the actual trade, and it is worth knowing before reaching for native SQL to avoid learning a JPQL construct.

Where I actually am

Honest position: every repository in my project uses derived methods only. I have not written a single @Query yet, because nothing I have needed has outgrown a method name.

That is worth saying plainly, because articles comparing two tools usually imply the author switches between them daily. I am writing this from the other side, the side where one tool still covers everything, and I wanted to know where its edge is before I hit it rather than after.

The rule I am taking from working that out: start with the derived method, and move to @Query at the point where the name stops being a sentence. It is about readability rather than capability, because capability rarely forces the decision. Derived methods express far more than most people use, so waiting until the name genuinely cannot express the query means writing several names nobody wants to read first.

Honest notes

There is no performance argument in this article, in either direction, and that is a choice rather than an oversight. For equivalent criteria the two produce equivalent queries. Nothing here was measured, so there is no number in this piece, and I would be careful with any article that hands you one without saying how it was produced.

Native queries buy real power and cost you the startup check and portability across databases. Worth paying sometimes. Not worth paying by accident.

This is also only about how the query is written, not what it fetches. A tidy derived method on a wide entity can still pull far more than you intended, which is a different problem and a different article.

Recap

Spring Data writes your query from your method name, and that name is a filename: excellent while it is a name, a liability once it becomes the content. Derived methods are checked at startup, which is a real benefit, but so is JPQL in @Query, so failing fast is not what separates them. Only native queries skip the check. Reach for @Query when the method name stops reading like a sentence, and reach for native SQL deliberately or not at all.

Where do you draw the line: at three conditions, at the first join, or only when a derived method genuinely cannot express the query? I suspect people are less consistent about this than they think.

P.S. If this was useful, subscribe. I write one piece like this every week.

Why My POST Request Became a GET

Vaishnavi Agrawal — Sat, 08 Aug 2026 08:57:14 +0000

Welcome back. This is the fourth article about my Purchase Decision API, after error handling, validation and the AI feature. Those three were about building it. This one is about the day it broke in a way that made no sense.

Postman said POST. The server said GET. Both were telling the truth.

The API worked on my machine. I deployed it to Railway, sent the first request, and got a 500. Not a validation error, not an auth error. Just a generic failure on the endpoint that starts the entire flow.

It took about a day to find, and the fix was three characters long. The interesting part is not the bug. It is that my own error handling had made the bug invisible, and I had written that error handling on purpose, and I had published an article about how nice it was.

The symptom that made no sense

Every POST and PUT failed on the deployed URL. POST /api/auth/register is where I fought it, because it is the first call in the flow and nothing else works until it does.

In Postman, the method dropdown said POST. The body was valid JSON. I screenshotted it more than once, because at some point I stopped trusting my own eyes.

The platform logs said something else:

HttpRequestMethodNotSupportedException: Request method 'GET' is not supported

Over and over. A GET error, on an endpoint I was only ever hitting with POST.

So I stopped believing the logs. Not consciously, but that is what it amounted to. The working theory was healthcheck pings, or a browser tab somewhere replaying an old URL. Anything except the obvious reading, which was that my request was arriving as a GET, because that was impossible.

The logs had the answer the whole time. I filed it as noise.

The false leads

The wrong turns are most of the story, so here they are.

I chased the JWT secret first. It was still the literal placeholder your-jwt-secret-value, twenty-one characters, under the minimum length HMAC needs. A genuine bug. I fixed it, redeployed, and the 500 did not move. That is the most expensive kind of red herring: a real problem that is not the problem. Finding it felt like progress and bought me nothing.

Then I decided the environment variables were not saving, because Railway's UI does not commit an edit until you click the tick and then deploy, which caught me twice. Then I decided I was testing a stale deploy, and for one round that was actually true: the commit that added the logging had not been pushed, so I was reading logs from old code.

Every theory had the same shape. The cause was out there, in the platform, somewhere I could not inspect. Which conveniently meant I never had to check the one thing I could inspect, which was what my server was actually receiving.

Bringing the error to me

The logs were flooded and I was tired of scrolling. So instead of going to the evidence, I brought the evidence to me.

My global handler was returning a polite, useless message. I changed it temporarily to say what had actually happened:

new ErrorResponse(500, "DEBUG: " + ex.getClass().getSimpleName() + " — " + ex.getMessage(), ...)

That is not code to leave in. Exception details in a response body are a security problem, and this came straight back out afterwards. But for one deploy, it turns your API client into your log viewer.

I sent the request again, as a POST, and read the response:

DEBUG: HttpRequestMethodNotSupportedException — Request method 'GET' is not supported

That was the moment. Not a healthcheck. Not a stray browser tab. The request I had just sent, arriving as a GET.

Three characters

I had typed the URL into Postman without a scheme. Postman filled in http://. The platform edge answered with a redirect to https://. Postman followed the redirect and re-issued the request as a GET, with no body.

The fix was typing https:// myself.

No config change. No nginx, no code. I had spent a day inside my application hunting a bug that happened before my application was ever reached.

Redirects are allowed to change your method

This is the part I did not know, and it is why the symptom looked impossible.

Think about posting a filled-in form to an office. The office has moved, so the forwarding service sends your letter on to the new address, except what it delivers is an empty envelope with a note saying this person would like to look at something. The address is honoured. The form you filled in, and the fact that you were submitting rather than browsing, are not.

That is what a redirect is permitted to do to a POST.

A 301 or a 302 is permission for a client to rewrite the request method to GET and drop the body. This is not the client misbehaving. RFC 7231 codified it because it is what browsers had always done, back when redirects mostly pointed at pages to look at rather than forms to submit. The specification is now in line with the behaviour.

The body disappears for the same reason. A GET is a request to fetch something, so a client that rewrites your POST into a GET has no reason to carry your JSON along. What reaches the server is not a damaged POST. It is a perfectly well formed GET that nobody meant to send.

Because this caused years of confusion, there are now codes that promise not to do it:

301, 302: the client may change your POST to a GET. Most do.
307, 308: the method is preserved. These exist specifically to fix the above.
303: always converts to GET, deliberately, for the redirect-after-submit pattern.

So "redirects break POST requests" is too broad to be true. The accurate version is narrower and more useful: a 301 or a 302 is allowed to turn your POST into a GET, and your client probably will.

I never captured which code my platform sent, so I will not claim one. The behaviour narrows it down on its own, which is useful to know: if a POST comes out the other side of a redirect as a GET, the response was one of the codes that permit it. A 307 or a 308 could not have produced what I saw.

Postman is one of those clients that rewrites. Its own documentation has a page titled "My request is redirected to a GET request", and its tracker has an issue describing my exact bug: http to https, POST arriving as GET. There is a per-request setting called Follow original HTTP method that stops this, and it is off by default.

Two practical things, then. Type the scheme, and turn that setting on. If you suspect this is happening to you, Postman's console shows the full redirect chain, so you can see the hop and the method change rather than inferring them.

My complaints desk shredded the evidence

Now the part that bothers me.

Spring already had the answer. HttpRequestMethodNotSupportedException has a natural response, and it is 405 Method Not Allowed. A 405 has the rejected method right there in it. A 405 on a request I had just sent as POST would have stopped me in minute one, because the contradiction would have been sitting in the response instead of buried in a log I had decided to distrust.

I never saw the 405. I had written this, and then written an article praising it:

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleAll(Exception ex) {
    return ResponseEntity.status(500)
        .body(new ErrorResponse(500, "Something went wrong", ...));
}

Every exception in the application, including the ones Spring throws with a precise status and a precise message, came out the other side as an anonymous 500. The complaints desk I was so pleased with was taking every complaint, writing "something went wrong" on a fresh form, and shredding the original.

The handler did not cause the bug. It replaced a self-diagnosing 405 with an anonymous 500, and destroyed the evidence. Then it did something slower and worse: it taught me my own error output was uninformative, which is why I dismissed those logs for a day.

I wrote nearly this same sentence three weeks ago, about an AI fallback that hid its own trigger and cost me days over one missing space. I had not finished learning it. A fallback that swallows silently and a handler that flattens everything are the same mistake at two sizes: the system keeps working well enough to stop telling you anything.

Honest notes

A few things this does not settle.

The catch-all is not wrong in itself. Something has to be the last line of defence, or an unexpected exception leaks a stack trace to a user. The fix is not deleting it. The fix is logging inside it, and letting framework exceptions that already carry a correct status and message pass through instead of collapsing them into a 500.

The DEBUG trick is a temporary tool, not a pattern. It puts internal exception detail into a response body. That is fine for one deploy on a project nobody is using yet. It is not fine anywhere real.

And the hole is still open. My OpenAPI config does not declare a server URL, so Swagger's "Try it out" resolves against whatever scheme the page was loaded with. One line, .addServersItem(new Server().url("https://...")), would close it. Writing this article is what made me go and check, and finding it missing is a more honest ending than claiming I had already tidied it up.

Recap

My POST request really was arriving as a GET. I had typed a URL without a scheme, the client defaulted to http, the platform redirected to https, and the client did what 301 and 302 allow: re-issued the request as a GET and dropped the body. Use 307 or 308 when the method has to survive, and turn on Follow original HTTP method in Postman.

Underneath that is the lesson I keep having to relearn. My global exception handler turned a 405 that named the problem into a 500 that named nothing, and a day of my time went into rediscovering what Spring had been ready to tell me immediately.

Handle your exceptions. Just do not let the handling become the reason you cannot see them.

When a framework exception already carries a precise status and message, like a 405 or a 415, do you pass it straight through to the client, or normalise everything into one consistent error shape and accept the loss? I have been going back and forth on this and would like to hear which side you land on.

P.S. If this was useful, subscribe. I write one piece like this every week.

Your AI Feature Should Not Break Your Endpoint

Vaishnavi Agrawal — Thu, 23 Jul 2026 18:08:02 +0000

Welcome back. This is the third article about my Purchase Decision API, after error handling and validation. This week the API got an AI feature, and this piece is about the design decision that mattered most.

Everyone is adding LLMs to their APIs right now. Almost nobody talks about what happens when the LLM is down.

I just built a purchase decision API. You tell it what you want to buy, and it tells you BUY, WAIT, or SKIP, with a score out of 100 and a savings plan. On top of that sits an AI-written explanation in friendly, human language.

The most important design decision I made was this: the AI cannot touch the verdict.

The obvious design, and why I did not use it

The tempting architecture is simple. Send the purchase details to an LLM and let it decide. One API call, no scoring logic to write, and the response already comes back in natural language.

I did not do it, for three reasons.

First, LLMs are not deterministic. The same purchase could get different verdicts on different days, and a decision API that changes its mind for no reason is not a decision API.

Second, it couples my uptime to someone else's. If the model provider has an outage, my endpoint has an outage.

Third, and this one settled it: a hallucinated verdict about someone's money is worse than no verdict at all.

A floor and a ceiling

So I split the response into two layers:

CEILING   LLM explanation          (nice to have, can fail)
FLOOR     score, verdict, plan     (pure Java, never fails)

The floor is everything the endpoint guarantees. My scoring engine is deterministic: it takes disposable income, price ratio, purchase type, and usage frequency, and produces a 0 to 100 score. Plain Java, no AI anywhere in that path. Same inputs, same score, every time.

The ceiling is everything that makes the response nicer but is allowed to fail. The AI explanation lives here, and only here.

Tell the model the answer

By the time the LLM is called, the verdict already exists. The model is not asked to decide anything. It is told the answer and asked only to explain it:

String prompt =
    "A user wants to buy '" + itemName + "' for ₹" + price + ". " +
    "Their monthly disposable income is ₹" + disposableIncome + ". " +
    "The affordability verdict is " + verdict + " with a score of " + score + "/100. " +
    "Explain this verdict in 2-3 friendly, non-judgmental sentences. " +
    "Do not repeat the numbers back mechanically — give practical, warm advice.";

That last line matters more than it looks. Without it, the model just recites your inputs back as a sentence, and you have spent an API call turning numbers into slightly longer numbers.

Notice what this structure buys you. Even if the model hallucinates, the worst it can produce is a badly worded explanation of a correct verdict. The blast radius of a bad AI response is prose, not money.

The fallback

The layers meet a second time at failure handling. The LLM call is wrapped so that any failure, whether a rate limit, a network error, or a malformed response, degrades to a template built from the same numbers:

try {
    return generateExplanation(prompt);
} catch (Exception e) {
    e.printStackTrace();   // more on this line in a second
    return buildFallbackExplanation(itemName, price, verdict, score, disposableIncome);
}

Here are the two outputs side by side, from the same request.

The AI version:

"It looks like investing in those Sony headphones might not be the best choice right now, considering your monthly income and expenditures..."

The fallback version:

"Based on your finances, buying Sony headphones for ₹30000 scored 45/100, giving a verdict of WAIT. This is measured against your monthly disposable income of ₹27000."

Worse prose. Identical information. The user loses warmth, never the answer. That is what graceful degradation actually means: the experience gets worse, the contract does not.

And yes, catch (Exception e) is normally a code smell. Here it is the point. This catch sits at the boundary of the optional layer, and there is no exception the AI layer can throw that should reach the user.

The bug that made me respect logging

My first version of this failed in a way I want to be honest about. Every response came back with the mechanical explanation, and I had no idea why. No errors, no crashes, nothing in the response to suggest a problem.

The fallback was working too well. It was hiding its own trigger.

Once I added logging, the cause turned out to be one missing character. I had written "Bearer" + apiKey. No space after Bearer. The auth header was malformed, OpenAI rejected every single call, and the fallback fired every time, exactly as designed.

That is the uncomfortable property of graceful degradation: a fallback that logs nothing is undebuggable. The system looks fine from the outside while quietly running in degraded mode forever. The rule I took away is short: log the failure, degrade anyway. Users should never see the AI layer fail, but you always should.

Honest notes

A few things this design does not solve.

The latency is still there when the AI is up. A synchronous LLM call adds real time to every response. For a low-traffic project that trade-off is acceptable; a high-traffic API would want the explanation generated asynchronously or cached, and that is not built here yet.

The broad catch is only right at this one boundary. Inside the scoring engine I still want real exceptions with real handling, the kind I wrote about in the error handling article. Catching everything is a deliberate choice for the optional layer, not a general style.

The fallback text is genuinely worse. Users notice the difference between warm advice and a template. An open question I have not answered yet: should the response admit degraded mode explicitly, with a field the client can read, or stay quiet about it?

I am still learning this area. This design is simply what survived contact with my own bugs.

Recap

The endpoint worked before the AI feature existed, and it has to keep working when the AI fails. So the response is split in two: a deterministic floor in plain Java that always returns the score, the verdict, and the plan, and an optional AI ceiling that explains the verdict when the model is reachable and falls back to a template when it is not. The model is told the answer instead of being asked for one, so a hallucination can only ever ruin the wording. And the fallback logs every failure, because a silent fallback once hid a one-character bug from me for days.

Let the AI reduce what your user has to read. Never let it decide what your system guarantees.

If you were building this, which would you choose: a response that openly admits degraded mode with an explicit field, or a fallback the user never knows about? I would like to hear arguments for either side.

P.S. If this was useful, subscribe. I write one piece like this every week.

Stop Bad Requests at the Door with Spring Validation

Vaishnavi Agrawal — Thu, 16 Jul 2026 04:19:48 +0000

Welcome to my newsletter. Every week I take one backend topic apart and write down what clicked, with working code from something I actually built. This week: validating REST requests.

Until I added validation, nothing in my register endpoint stopped a blank email and an empty password from sailing straight through. The first thing to complain would have been the database, five layers too late and in an error message no client could use.

For a while I handled this the obvious way: if-blocks at the top of the controller. It worked, but it looked exactly like my error handling before last week's refactor: the same checks copied into every endpoint, and controllers filling up with code that had nothing to do with their actual job.

Fixing it properly forced me to understand something more useful than any annotation: what actually happens to a request between the raw JSON arriving and my method running. Once I could see that pipeline, I knew where every kind of "bad" belongs. That is what this article is really about.

The journey of a bad request

When a POST hits my register endpoint, my controller method is not the first stop. The request has to survive three checkpoints, and each one rejects a different kind of bad:

Deserialization. Jackson turns the raw JSON into my RegisterRequest object. If the JSON is malformed, or a field cannot become its Java type (text where a number belongs), the journey ends here. Validation never runs, because there is no object to validate yet.
Validation. The object exists; now @Valid checks whether its contents follow my rules. Is the email shaped like an email? Is the password long enough? No database, no business context, just the data judging itself.
Business rules. Only now does my method run, and the service decides things data alone cannot: does this email already exist? That check needs the database, which is why it lives in the service layer and throws my EmailAlreadyExistsException from last week, not a validation error.

The distinction that clicked for me: validation answers "is this data well-formed?", business rules answer "is this data acceptable right now?". "Email must look like an email" is checkpoint 2. "Email must not be taken" is checkpoint 3. Put a check at the wrong checkpoint and you get code that either cannot do its job or does it in the wrong place.

Each checkpoint also fails with a different exception, which matters later: checkpoint 1 throws HttpMessageNotReadableException, checkpoint 2 throws MethodArgumentNotValidException, checkpoint 3 throws whatever my service decides. Three kinds of bad, three signals.

The one dependency everyone forgets

Before any of checkpoint 2 works, the gotcha that costs people an hour: validation is not included in the web starter. Since Spring Boot 2.3, spring-boot-starter-web ships without it, so you can write validation annotations all day and @Valid will silently do nothing.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-validation</artifactId>
</dependency>

If your validation "does not work", check this first. In Spring Boot 3 the annotations live in jakarta.validation, not the javax.validation you will still see in older tutorials.

Checkpoint 2 in practice: rules live on the DTO

Bean Validation puts the rules on the data itself. My real RegisterRequest:

@Data
@AllArgsConstructor
@NoArgsConstructor
public class RegisterRequest {

    @NotBlank(message = "Name is required")
    @Size(max = 100, message = "Name cannot exceed 100 characters")
    private String name;

    @NotBlank(message = "Email is required")
    @Email(message = "Email should be valid")
    private String email;

    @NotBlank(message = "Password is required")
    @Size(min = 8, message = "Password must be at least 8 characters")
    @Pattern(
            regexp = "^(?=.*[0-9])(?=.*[A-Z])(?=.*[!@#$%^&*()_+\\-=\\[\\]{};':\"\\\\|,.<>/?]).*$",
            message = "Password must contain at least one number, one uppercase letter, and one symbol"
    )
    private String password;
}

The rules sit next to the fields they protect, the message values speak to the API caller rather than to me, and the controller knows none of this exists. The regex is three lookaheads (a digit, an uppercase letter, a symbol); @Size handles length separately, so each failure produces its own message.

One subtlety worth knowing: @NotBlank and @NotNull are not interchangeable. A password of three spaces passes @NotNull happily. @NotBlank means "not null, and not just whitespace", which is a text-only concept. That difference caused my favorite bug of this refactor, but that story comes later.

Turning the checkpoint on is one word in the controller:

@PostMapping("/register")
public ResponseEntity<AuthResponse> register(@Valid @RequestBody RegisterRequest registerRequest) {
    AuthResponse response = authService.register(registerRequest);
    return ResponseEntity.status(201).body(response);
}

@Valid tells Spring to run the DTO's constraints after deserialization and before my method body. If anything fails, my method never runs, and the bad data never touches the service layer.

What a failure actually contains

When checkpoint 2 fails, Spring does not hand you a string. MethodArgumentNotValidException carries a BindingResult, which holds one FieldError per broken rule: the field name, the rejected value, and the message from the annotation. And rules fail independently, even on the same field. A blank password breaks @NotBlank, @Size, and @Pattern all at once, which is three FieldErrors from a single field. Validation reports every broken rule, not just the first one it finds.

That structure is raw material. My job is to decide what shape the client sees, and I already made that decision last week: everything returns my ErrorResponse class. So the handler mines the FieldErrors and folds them into that shape:

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
    String message = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.joining(", "));

    return ResponseEntity.status(400).body(
            new ErrorResponse(400, message, LocalDateTime.now())
    );
}

One new method in the same GlobalExceptionHandler, no new error system. The client gets:

{
  "status": 400,
  "message": "email: Email is required, password: Password must be at least 8 characters",
  "timestamp": "2026-07-14T18:20:41"
}

Same shape as a 404, same shape as a 409. A client that could parse my errors last week parses these without learning anything new.

The checkpoint I forgot to handle

Writing this article exposed a hole in my own setup. My handler covered checkpoint 2, and my custom exceptions covered checkpoint 3. But checkpoint 1 had nothing: no handler in the class mentioned HttpMessageNotReadableException, which means malformed JSON had no guaranteed answer, let alone the right one.

The right one is a 400. A 500 says "we broke"; malformed JSON means "you sent garbage". The fix is the same pattern a third time:

@ExceptionHandler(HttpMessageNotReadableException.class)
public ResponseEntity<ErrorResponse> handleUnreadable(HttpMessageNotReadableException ex) {
    return ResponseEntity.status(400).body(
            new ErrorResponse(400, "Request body is missing or malformed", LocalDateTime.now())
    );
}

Now all three checkpoints report through the same desk, each with an honest status code. That is the real payoff of understanding the pipeline: when a new kind of failure shows up, you know exactly which checkpoint it belongs to and where its handler goes.

Two mistakes that taught me the rules

Mistake one: @NotBlank on a number. My DecisionRequest has a BigDecimal price field. I annotated it @NotBlank like the String fields around it, sent a request, and got a 500 with UnexpectedTypeException: No validator could be found for constraint. Not a validation failure. A crash.

The reason follows from the whitespace point earlier: @NotBlank is a text-only concept, so it only works on CharSequence types. There is no such thing as a whitespace BigDecimal. For anything that is not text, the right annotation is @NotNull, and if the value itself matters there are number-specific checks like @Positive and @DecimalMin. My rule of thumb now: @NotBlank for text, @NotNull for everything else, @NotEmpty for collections that need at least one element.

Mistake two: the same rules everywhere. My login DTO originally had the full password @Pattern on it, copied straight from RegisterRequest. Looks consistent. Then I realized what it would do: if I ever tightened the complexity rule, every existing user whose password predates the rule would fail validation at login. They could not even get in to change it.

Login now only checks that email and password are present. Registration is where strength rules belong, because that is the only moment a password is being chosen. Same field, different context, different rules. Validation belongs to the use case, not to the field.

Honest notes

One simplification to own up to: in a secured app the request meets the security filter chain before any of these checkpoints. My register endpoint is open (permitAll), so the three checkpoints are the whole story for this request, but on a protected endpoint the filters get the first word. Constraints placed directly on @RequestParam or @PathVariable arguments fail with yet another exception (HandlerMethodValidationException in current Spring), so query-parameter validation needs its own handler; I have not needed it yet. Bean Validation also goes deeper than I have gone: nested objects, class-level rules that compare two fields, fully custom validators. I will write about those when my API actually uses them.

Recap

A request crosses three checkpoints: deserialization, validation, business rules. Each rejects a different kind of bad, each fails with a different exception, and all three should report through the same handler in the same error shape. Validation itself is one dependency, annotations with human-readable messages on the DTO, and @Valid on the parameter. And the two rules my mistakes taught me: match the annotation to the field's type, and match the rules to the use case.

When a request fails three validations at once, my API returns all three messages joined in one string. How do you handle it: first error only, everything in one string, or a structured per-field map? Tell me in the comments. I am genuinely curious what clients prefer.

P.S. If this was useful, subscribe on Substack. I write one piece like this every week.

How I Cleaned Up Error Handling in My Spring Boot API

Vaishnavi Agrawal — Thu, 09 Jul 2026 15:20:38 +0000

Welcome to my newsletter. Every week I take one backend topic, learn it properly, and write down what clicked, with working code from something I actually built. This week: exception handling.

When I built the first version of my Purchase Decision API, my error handling was scattered everywhere. Almost every controller method had its own try-catch block. Looking up a user that did not exist returned one error shape, registering with an existing email returned another, and anything unexpected leaked Spring's default error response to the client.

None of it was broken, exactly. It was worse: it was inconsistent. Every new endpoint meant copying error-handling code from an older one and hoping I kept the format the same. I usually did not.

Here is the pattern I settled on instead: custom exceptions plus one global handler with @ControllerAdvice. It is a small change, and it cleaned up my controllers more than anything else I have done to them.

The idea in one picture

Think of a store where every employee handles complaints their own way. One offers a refund, one apologizes and does nothing, and one argues. Customers get a different experience depending on who they happen to reach. Now put a single trained person at a complaints desk and give every employee the same instruction: send complaints there. Suddenly, every complaint gets the same treatment.

@ControllerAdvice is the complaints desk. It is a global exception handler that catches exceptions thrown anywhere in your controllers and handles them in one central place, instead of you repeating try-catch blocks in every controller method. Your controllers stay focused on their actual job, and every endpoint returns errors in the same format.

Step 1: name your errors

The first thing I did was turn my failure cases into small, specific exception classes. In my API, the three that come up constantly are a missing user, a duplicate email at registration, and a wrong password:

public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(String message) {
        super(message);
    }
}

public class EmailAlreadyExistsException extends RuntimeException {
    public EmailAlreadyExistsException(String message) {
        super(message);
    }
}

public class InvalidPasswordException extends RuntimeException {
    public InvalidPasswordException(String message) {
        super(message);
    }
}

They extend RuntimeException so I can throw them from my service layer without declaring them everywhere. The service just states what went wrong:

User user = userRepository.findByEmail(email)
        .orElseThrow(() -> new UserNotFoundException("No user with email " + email));

Notice what the service does not do: it does not know or care what HTTP status this becomes. That decision lives somewhere else.

Step 2: decide what an error looks like

Before the handler, I defined one shape that every error response uses. Mine is small:

public record ErrorResponse(
        int status,
        String error,
        String message,
        Instant timestamp
) {}

A client calling my API now knows that any error, from any endpoint, looks like this:

{
  "status": 404,
  "error": "Not Found",
  "message": "No user with email priya@example.com",
  "timestamp": "2026-07-08T14:32:10Z"
}

That consistency is the whole point. Frontend code can handle errors in one place too, because it can rely on the shape.

Step 3: the complaints desk itself

One class, annotated with @ControllerAdvice, catches each exception and maps it to the right status code:

@Slf4j
@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleUserNotFound(UserNotFoundException ex) {
        return build(HttpStatus.NOT_FOUND, ex.getMessage());
    }

    @ExceptionHandler(EmailAlreadyExistsException.class)
    public ResponseEntity<ErrorResponse> handleEmailExists(EmailAlreadyExistsException ex) {
        return build(HttpStatus.CONFLICT, ex.getMessage());
    }

    @ExceptionHandler(InvalidPasswordException.class)
    public ResponseEntity<ErrorResponse> handleInvalidPassword(InvalidPasswordException ex) {
        return build(HttpStatus.UNAUTHORIZED, ex.getMessage());
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex) {
        // log the real error for ourselves, return something safe to the client
        log.error("Unexpected error", ex);
        return build(HttpStatus.INTERNAL_SERVER_ERROR, "Something went wrong on our side.");
    }

    private ResponseEntity<ErrorResponse> build(HttpStatus status, String message) {
        ErrorResponse body = new ErrorResponse(
                status.value(), status.getReasonPhrase(), message, Instant.now());
        return ResponseEntity.status(status).body(body);
    }
}

Picking the status codes was its own small lesson. A missing user is 404 Not Found. A duplicate email is 409 Conflict, because the request is fine but it collides with existing state. A wrong password is 401 Unauthorized. Before this refactor I returned 400 for almost everything, which technically worked and helped nobody.

The last handler matters most. Anything I did not predict gets caught, logged with its stack trace on the server, and turned into a generic 500 for the client. The client never sees internals, and I still get the full details in my logs.

What actually changed

My controllers went from this kind of thing:

try {
    UserDto user = userService.getByEmail(email);
    return ResponseEntity.ok(user);
} catch (UserNotFoundException ex) {
    return ResponseEntity.status(404).body(/* hand-built error */);
}

to this:

return ResponseEntity.ok(userService.getByEmail(email));

Without the global handler, I would repeat the same error-handling code in every controller method and risk formatting errors differently each time. With it, I write each error's handling once, every endpoint returns errors the same way, and my controllers stay focused on their actual logic.

Honest notes

Two things I want to be upfront about. First, this is the pattern that works for my project's current size; I am sure there are refinements I have not needed yet. Second, Spring Boot 3 has a built-in ProblemDetail type that follows an RFC standard for error bodies. I have not used it in this project, and trying it is on my list. If you use it and like it, I would genuinely like to hear why.

Recap

Scattered try-catch blocks mean duplicated code and inconsistent errors. The fix I settled on: specific exception classes thrown from the service layer, one ErrorResponse shape, and one @ControllerAdvice class that maps each exception to the right status code, with a logging catch-all so nothing leaks. Controllers get shorter, clients get predictable errors, and adding a new error case is one small handler method instead of another copy-pasted try-catch.

How do you shape your error responses, and did you settle on something different? Tell me in the comments. I compare notes gladly.

P.S. If this was useful, subscribe. I write one piece like this every week.