Loading published curriculum…

11 · REST APIs / LESSON 50 OF 102

Consistent API errors

Give clients safe, actionable failures.

Before this lesson: Request validation

Understand the topic

@RestControllerAdvice centralizes exception mapping. ProblemDetail provides a standard problem response. Select statuses based on the actual failure rather than returning 200 with an error string.

Keep SQL details, stack traces, credentials, and internal hosts out of public responses. Log unexpected failures server-side. Map known exception types narrowly; unexpected failures should not be mislabeled as invalid client input.

EXAMPLE · JAVA

src/main/java/com/example/tasks/ApiErrors.java

package com.example.tasks;
import org.springframework.http.*;
import org.springframework.web.bind.annotation.*;
@RestControllerAdvice
public class ApiErrors {
    @ExceptionHandler(IllegalArgumentException.class)
    public ProblemDetail invalidInput(IllegalArgumentException error) {
        return ProblemDetail.forStatusAndDetail(
            HttpStatus.BAD_REQUEST, "The request contains an invalid value.");
    }
}

What to expect

An IllegalArgumentException becomes a safe 400 response. Framework field-validation errors retain their handling until you add a dedicated mapping.

YOUR TURN

Put it into practice

  1. 01Add a TaskNotFoundException mapped to 404.
  2. 02Return safe field names for validation errors.
  3. 03Test that an unexpected failure remains a server error.

Pass a quiz or complete a lab to check today’s streak. Each lesson counts once per day, including when you review it later.

UNDER THE HOOD

Build the mental model

Errors are part of the API, but internal debugging information belongs in controlled logs.

  1. 01Use stable error categories and appropriate statuses so clients can respond programmatically. Avoid requiring them to parse an English sentence.
  2. 02Map known domain exceptions narrowly. Catch-all handlers should still produce a server error and preserve diagnostic logging.
  3. 03Correlate a public request ID with server logs; do not return stack traces or SQL queries.

A mistake worth avoiding

Returning 200 for every error breaks monitoring and client retries.

DEBUGGING ROOM

Something broke. Where do you look?

An outage is reported as hundreds of successful requests.

Before revealing the diagnosis, write down your first investigation step.

CHECK YOUR UNDERSTANDING

A task ID does not exist. Which status is normally appropriate?

Choose one answer

BUILD IT YOURSELF

Define an error catalog

  1. 1.Document invalid input, missing resource, conflict, and unexpected failure.
  2. 2.Implement narrow exception mappings.
  3. 3.Add HTTP assertions for statuses and safe error bodies.

Acceptance checklist

Lab completion is your self-report. Knowledge checks do not certify project quality.

RETRIEVE IT FROM MEMORY

Which error details are safe for a client to see?

Revisit this lesson in three days after a successful check or lab.

Ready for the next step?

Choose between 400, 404, 409, and 500.

Reading is separate from passing a knowledge check or completing a lab.

Go deeper · official references