DEV Community: Vaishnavi Agrawal

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.