problem-details-rfc9457

Name: problem-details-rfc9457
Author: rrezartprebreza

174stars33forks

How to install problem-details-rfc9457?

rrezartprebreza/spring-boot-skills/problem-details-rfc9457

$npx -y skills add rrezartprebreza/spring-boot-skills --skill problem-details-rfc9457

Installs into the current project.

Summary

Use when implementing error handling, exception mappers, or error response formatting. Enforces RFC 9457 (Problem Details for HTTP APIs) using Spring's built-in ProblemDetail.

Files · 1

View on GitHub

SKILL.md

1	# Problem Details — RFC 9457
2
3	Spring Boot 3.x includes native RFC 9457 support via `ProblemDetail`.
4
5	## Enable in application.yml
6
7	```yaml
8	spring:
9	mvc:
10	problemdetails:
11	enabled: true # enables Spring's built-in RFC 9457 handler
12	```
13
14	## ProblemDetail Response Shape
15
16	```json
17	{
18	"type": "https://api.example.com/errors/order-not-found",
19	"title": "Order Not Found",
20	"status": 404,
21	"detail": "No order found with id: 550e8400-e29b-41d4-a716-446655440000",
22	"instance": "/api/v1/orders/550e8400-e29b-41d4-a716-446655440000",
23	"errorCode": "ORDER_NOT_FOUND",
24	"timestamp": "2026-04-13T10:00:00Z"
25	}
26	```
27
28	## Global Exception Handler
29
30	```java
31	@RestControllerAdvice
32	public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
33
34	@ExceptionHandler(EntityNotFoundException.class)
35	public ProblemDetail handleNotFound(EntityNotFoundException ex, HttpServletRequest request) {
36	ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
37	problem.setType(URI.create("https://api.example.com/errors/not-found"));
38	problem.setTitle("Resource Not Found");
39	problem.setInstance(URI.create(request.getRequestURI()));
40	problem.setProperty("errorCode", "NOT_FOUND");
41	problem.setProperty("timestamp", Instant.now());
42	return problem;
43	}
44
45	@ExceptionHandler(BusinessRuleViolationException.class)
46	public ProblemDetail handleBusinessRule(BusinessRuleViolationException ex, HttpServletRequest request) {
47	ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
48	problem.setType(URI.create("https://api.example.com/errors/business-rule"));
49	problem.setTitle("Business Rule Violation");
50	problem.setInstance(URI.create(request.getRequestURI()));
51	problem.setProperty("errorCode", ex.getErrorCode());
52	problem.setProperty("timestamp", Instant.now());
53	return problem;
54	}
55
56	@Override
57	protected ResponseEntity<Object> handleMethodArgumentNotValid(
58	MethodArgumentNotValidException ex, HttpHeaders headers,
59	HttpStatusCode status, WebRequest request
60	) {
61	ProblemDetail problem = ProblemDetail.forStatusAndDetail(
62	HttpStatus.BAD_REQUEST, "Request validation failed");
63	problem.setType(URI.create("https://api.example.com/errors/validation"));
64	problem.setTitle("Validation Failed");
65	problem.setProperty("timestamp", Instant.now());
66	problem.setProperty("violations", ex.getBindingResult().getFieldErrors().stream()
67	.map(e -> Map.of("field", e.getField(), "message", e.getDefaultMessage()))
68	.toList());
69	return ResponseEntity.badRequest().body(problem);
70	}
71
72	@ExceptionHandler(Exception.class)
73	public ProblemDetail handleGeneric(Exception ex, HttpServletRequest request) {
74	ProblemDetail problem = ProblemDetail.forStatusAndDetail(
75	HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred");
76	problem.setType(URI.create("https://api.example.com/errors/internal"));
77	problem.setTitle("Internal Server Error");
78	problem.setInstance(URI.create(request.getRequestURI()));
79	problem.setProperty("timestamp", Instant.now());
80	// Don't expose ex.getMessage() in production — log it instead
81	log.error("Unhandled exception at {}", request.getRequestURI(), ex);
82	return problem;
83	}
84	}
85	```
86
87	## Custom Domain Exceptions
88
89	```java
90	// Base exception
91	public abstract class DomainException extends RuntimeException {
92	private final String errorCode;
93
94	protected DomainException(String errorCode, String message) {
95	super(message);
96	this.errorCode = errorCode;
97	}
98
99	public String getErrorCode() { return errorCode; }
100	}
101
102	// Specific exceptions
103	public class OrderNotFoundException extends DomainException {
104	public OrderNotFoundException(UUID orderId) {
105	super("ORDER_NOT_FOUND", "Order not found: " + orderId);
106	}
107	}
108
109	public class InsufficientInventoryException extends DomainException {
110	public InsufficientInventoryException(UUID productId, int requested, int available) {
111	super("INSUFFICIENT_INVENTORY",
112	"Insufficient inventory for product %s: requested %d, available %d"
113	.formatted(productId, requested, available));
114	}
115	}
116	```
117
118	## Content Negotiation
119
120	Clients can request problem details explicitly with `Accept: application/problem+json`. Spring handles this automatically when `problemdetails.enabled: true` — your handler returns `ProblemDetail` and Spring sets the correct `Content-Type: application/problem+json`.
121
122	## ProblemDetail vs ApiResponse Envelope
123
124	\| Use Case \| Approach \|
125	\|---\|---\|
126	\| Er

People who liked this also viewed

6 picks

Type

problem-details-rfc9457

174stars33forks

View on GitHub

How to install problem-details-rfc9457?

rrezartprebreza/spring-boot-skills/problem-details-rfc9457

$npx -y skills add rrezartprebreza/spring-boot-skills --skill problem-details-rfc9457

Installs into the current project.

Summary

Use when implementing error handling, exception mappers, or error response formatting. Enforces RFC 9457 (Problem Details for HTTP APIs) using Spring's built-in ProblemDetail.

Files · 1

View on GitHub

SKILL.md

1	# Problem Details — RFC 9457
2
3	Spring Boot 3.x includes native RFC 9457 support via `ProblemDetail`.
4
5	## Enable in application.yml
6
7	```yaml
8	spring:
9	mvc:
10	problemdetails:
11	enabled: true # enables Spring's built-in RFC 9457 handler
12	```
13
14	## ProblemDetail Response Shape
15
16	```json
17	{
18	"type": "https://api.example.com/errors/order-not-found",
19	"title": "Order Not Found",
20	"status": 404,
21	"detail": "No order found with id: 550e8400-e29b-41d4-a716-446655440000",
22	"instance": "/api/v1/orders/550e8400-e29b-41d4-a716-446655440000",
23	"errorCode": "ORDER_NOT_FOUND",
24	"timestamp": "2026-04-13T10:00:00Z"
25	}
26	```
27
28	## Global Exception Handler
29
30	```java
31	@RestControllerAdvice
32	public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {
33
34	@ExceptionHandler(EntityNotFoundException.class)
35	public ProblemDetail handleNotFound(EntityNotFoundException ex, HttpServletRequest request) {
36	ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.NOT_FOUND, ex.getMessage());
37	problem.setType(URI.create("https://api.example.com/errors/not-found"));
38	problem.setTitle("Resource Not Found");
39	problem.setInstance(URI.create(request.getRequestURI()));
40	problem.setProperty("errorCode", "NOT_FOUND");
41	problem.setProperty("timestamp", Instant.now());
42	return problem;
43	}
44
45	@ExceptionHandler(BusinessRuleViolationException.class)
46	public ProblemDetail handleBusinessRule(BusinessRuleViolationException ex, HttpServletRequest request) {
47	ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
48	problem.setType(URI.create("https://api.example.com/errors/business-rule"));
49	problem.setTitle("Business Rule Violation");
50	problem.setInstance(URI.create(request.getRequestURI()));
51	problem.setProperty("errorCode", ex.getErrorCode());
52	problem.setProperty("timestamp", Instant.now());
53	return problem;
54	}
55
56	@Override
57	protected ResponseEntity<Object> handleMethodArgumentNotValid(
58	MethodArgumentNotValidException ex, HttpHeaders headers,
59	HttpStatusCode status, WebRequest request
60	) {
61	ProblemDetail problem = ProblemDetail.forStatusAndDetail(
62	HttpStatus.BAD_REQUEST, "Request validation failed");
63	problem.setType(URI.create("https://api.example.com/errors/validation"));
64	problem.setTitle("Validation Failed");
65	problem.setProperty("timestamp", Instant.now());
66	problem.setProperty("violations", ex.getBindingResult().getFieldErrors().stream()
67	.map(e -> Map.of("field", e.getField(), "message", e.getDefaultMessage()))
68	.toList());
69	return ResponseEntity.badRequest().body(problem);
70	}
71
72	@ExceptionHandler(Exception.class)
73	public ProblemDetail handleGeneric(Exception ex, HttpServletRequest request) {
74	ProblemDetail problem = ProblemDetail.forStatusAndDetail(
75	HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred");
76	problem.setType(URI.create("https://api.example.com/errors/internal"));
77	problem.setTitle("Internal Server Error");
78	problem.setInstance(URI.create(request.getRequestURI()));
79	problem.setProperty("timestamp", Instant.now());
80	// Don't expose ex.getMessage() in production — log it instead
81	log.error("Unhandled exception at {}", request.getRequestURI(), ex);
82	return problem;
83	}
84	}
85	```
86
87	## Custom Domain Exceptions
88
89	```java
90	// Base exception
91	public abstract class DomainException extends RuntimeException {
92	private final String errorCode;
93
94	protected DomainException(String errorCode, String message) {
95	super(message);
96	this.errorCode = errorCode;
97	}
98
99	public String getErrorCode() { return errorCode; }
100	}
101
102	// Specific exceptions
103	public class OrderNotFoundException extends DomainException {
104	public OrderNotFoundException(UUID orderId) {
105	super("ORDER_NOT_FOUND", "Order not found: " + orderId);
106	}
107	}
108
109	public class InsufficientInventoryException extends DomainException {
110	public InsufficientInventoryException(UUID productId, int requested, int available) {
111	super("INSUFFICIENT_INVENTORY",
112	"Insufficient inventory for product %s: requested %d, available %d"
113	.formatted(productId, requested, available));
114	}
115	}
116	```
117
118	## Content Negotiation
119
120	Clients can request problem details explicitly with `Accept: application/problem+json`. Spring handles this automatically when `problemdetails.enabled: true` — your handler returns `ProblemDetail` and Spring sets the correct `Content-Type: application/problem+json`.
121
122	## ProblemDetail vs ApiResponse Envelope
123
124	\| Use Case \| Approach \|
125	\|---\|---\|
126	\| Er

People who liked this also viewed

6 picks

Type