exception-handling

Implements a typed exception hierarchy and RFC 7807 ProblemDetail error contract for Spring Boot services.

Updated Jun 25, 2026
One-click install
npx skills add https://github.com/oriddd/ai-toolkit --skill exception-handling-oriddd
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: exception-handling
Source: https://github.com/oriddd/ai-toolkit/tree/main/copilot/public/skills/exception-handling
Command: npx skills add https://github.com/oriddd/ai-toolkit --skill exception-handling-oriddd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Spring Boot services often leak inconsistent error responses — raw strings, ad-hoc JSON, or unhandled RuntimeExceptions — making APIs hard for clients to consume and debug. This Skill establishes a single project-wide error contract: typed domain exceptions, a centralized message catalogue, and one @RestControllerAdvice that maps every exception to a standards-compliant RFC 7807 ProblemDetail response. ## Core Features & Use Cases - Typed Domain Exception Hierarchy: Generates a checked base exception plus subclasses (BadRequest, Forbidden, NotFound) whose identity determines the HTTP status mapping. - Centralized ExceptionMessages Catalogue: All user-facing messages live as static constants formatted with java.text.MessageFormat, keeping messages uniform and i18n-ready. - RFC 7807 @RestControllerAdvice: A single handler extending ResponseEntityExceptionHandler maps each exception to a ProblemDetail with the correct status, while preserving Spring's built-in handlers for validation errors. - Use Case: When building a new Spring Boot microservice, apply this Skill to scaffold the full exception package — exceptions, message constants, and the global handler — so every endpoint returns consistent 400/403/404/500 ProblemDetail responses from day one. ## Quick Start Apply the exception-handling skill to generate the exception package, message constants, and global ProblemDetail handler for this Spring Boot service.

Frequently Asked Questions about exception-handling

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I return RFC 7807 ProblemDetail responses in Spring Boot?

Create a @RestControllerAdvice that extends ResponseEntityExceptionHandler and add @ExceptionHandler methods returning ProblemDetail.forStatus(status) with title and detail set. Spring Boot 3 supports ProblemDetail natively, so no extra libraries are required.

How should I structure a custom exception hierarchy in Spring Boot?

Define one checked base exception per domain, then subclass it per HTTP status (BadRequest, Forbidden, NotFound). Provide only (String) and (String, Throwable) constructors and never add status fields — the exception's type identity drives the mapping in the advice.

Does Spring Boot 3 support ProblemDetail without extra libraries?

Yes. Spring Boot 3 includes org.springframework.http.ProblemDetail and ResponseEntityExceptionHandler out of the box, so a full RFC 7807 error contract works with stock framework primitives and no private or third-party libraries.

Should I throw RuntimeException for expected business errors?

No. Throwing RuntimeException for expected failures hides error paths from callers and defeats typed advice mapping. Use checked domain exception subclasses so the compiler enforces handling and the advice maps each subclass to the correct HTTP status.

Where should third-party exceptions be mapped to HTTP statuses?

Map third-party exceptions in the @RestControllerAdvice, not in the service layer. Services should rethrow as-is or wrap them into a domain exception, keeping HTTP concerns out of business logic and all status mapping in one place.