Error Handling Spring Boot Starter

https://github.com/wimdeblauwe/error-handling-spring-boot-starter
Admin
A Spring Boot starter that provides opinionated, consistent error handling and response formatting...
Tokens:109,208
Snippets:801
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Example response for BadCredentialsException

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-framework.md

JSON response example for BadCredentialsException with code BAD_CREDENTIALS and message Bad credentials.

```json
{
  "code": "BAD_CREDENTIALS",
  "message": "Bad credentials"
}
```

--------------------------------

### Example ProblemDetail for TODO_NOT_FOUND

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/problem-detail-factory.md

Example usage showing the resulting ProblemDetail fields for a TODO_NOT_FOUND error with default prefix and kebab-case conversion enabled.

```java
ProblemDetail detail = problemDetailFactory.build(errorResponse);
detail.getType();   // URI "todo-not-found"  (type = new URI(prefix + kebabCase(code)), prefix defaults to "")
detail.getStatus(); // 404
detail.getDetail(); // "Todo 42 not found"
```

--------------------------------

### ApiErrorResponseCustomizer Example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/error-handling-facade.md

Shows how to implement an ApiErrorResponseCustomizer to customize every error response, for example adding a trace ID from MDC.

```APIDOC
## ApiErrorResponseCustomizer Example

### Description
Customizes every error response produced by the facade. Implementations are applied in declaration order.

### Interface
```java
public interface ApiErrorResponseCustomizer {
    void customize(ApiErrorResponse response);
}
```

### Example Implementation
```java
@Component
public class TraceIdCustomizer implements ApiErrorResponseCustomizer {
    @Override
    public void customize(ApiErrorResponse response) {
        response.addErrorProperty("traceId", MDC.get("traceId"));
    }
}
```
```

--------------------------------

### Example missing request parameter response

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-web.md

Shows the JSON response for a GET /todos?limit= request when the required 'limit' parameter is missing. The status is 400 (default) and the error properties include parameterName and parameterType.

```java
// @GetMapping("/todos")
// public void list(@RequestParam("limit") int limit) { ... }
```

```json
{
  "code": "VALIDATION_FAILED",
  "message": "Required request parameter 'limit' for method parameter type int is not present",
  "parameterName": "limit",
  "parameterType": "int"
}
```

--------------------------------

### Example @Validated service method

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-validation.md

Example service method that triggers ConstraintViolationException when validation fails.

```java
@Service
@Validated
public class TodoService {
    public void update(@NotNull @Min(1) Long id) { ... }
}
```

--------------------------------

### Example exception extending RuntimeException (ApplicationException)

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example exception class that extends RuntimeException, used in the context of resetting back to default messaging.

```java
public class ApplicationException extends RuntimeException {}
```

--------------------------------

### Custom status mapper example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/mappers.md

Shows how to contribute a custom mapper by implementing the SPI and annotating with @Component. The example handles MyRemoteApiException and extracts the status from its remote status code.

```java
@Component
public class MyStatusMapper implements HttpResponseStatusFromExceptionMapper {
    @Override
    public boolean canExtractResponseStatus(Throwable exception) {
        return exception instanceof MyRemoteApiException;
    }

    @Override
    public HttpStatusCode getResponseStatus(Throwable exception) {
        return HttpStatusCode.valueOf(((MyRemoteApiException) exception).getRemoteStatusCode());
    }
}
```

--------------------------------

### Problem Detail response with type prefix

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example response when the type prefix is configured. The type field becomes a fully qualified URI.

```json
{
  "type": "https://api.example.com/errors/user-not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Could not find user with id 123"
}
```

--------------------------------

### Example exception extending RuntimeException

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example exception class that extends RuntimeException, used to demonstrate superclass hierarchy search.

```java
public class MyException extends RuntimeException {}
```

--------------------------------

### Example request handler for @Valid body

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-validation.md

Shows a commented @PostMapping handler with @Valid @RequestBody CreateTodoRequest, used as the request side of the example response.

```java
// @PostMapping("/todos")
// public void create(@Valid @RequestBody CreateTodoRequest body) { ... }
```

--------------------------------

### Example JSON error response for GET /todos/abc

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-web.md

Shows the JSON response when a path variable of type Long receives 'abc'. Includes code, message, property, rejectedValue, and expectedType fields.

```json
{
  "code": "ARGUMENT_TYPE_MISMATCH",
  "message": "Method parameter 'id': Failed to convert value of type 'java.lang.String' to required type 'java.lang.Long'...",
  "property": "id",
  "rejectedValue": "abc",
  "expectedType": "java.lang.Long"
}
```

--------------------------------

### YAML configuration for error-handling-spring-boot-starter

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/configuration.md

Example configuration for the error-handling-spring-boot-starter. It enables error handling, disables problem detail format, sets logging to WITH_STACKTRACE, defines log levels for 4xx and 5xx, specifies full stacktrace classes and HTTP statuses, sets default error code strategy to ALL_CAPS, adds path to error, searches super class hierarchy, customizes JSON field names, and maps exception classes to custom codes, messages, and HTTP statuses.

```yaml
error:
  handling:
    enabled: true
    use-problem-detail-format: false
    http-status-in-json-response: true
    exception-logging: WITH_STACKTRACE
    log-levels:
      "4xx": warn
      "5xx": error
    full-stacktrace-classes:
      - com.example.MyCriticalException
    full-stacktrace-http-statuses:
      - "5xx"
    default-error-code-strategy: ALL_CAPS
    add-path-to-error: true
    search-super-class-hierarchy: true
    json-field-names:
      code: errorCode
      message: errorMessage
    codes:
      com.example.MyException: MY_ERROR
    messages:
      com.example.MyException: Something went wrong
    http-statuses:
      com.example.MyException: 418
```

--------------------------------

### Basic construction and population example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/api-error-response.md

Shows how to create an ApiErrorResponse, add a field error, and add an error property. The resulting JSON is shown in the next snippet.

```java
ApiErrorResponse response = new ApiErrorResponse(HttpStatus.BAD_REQUEST, "VALIDATION_FAILED", "Validation failed");
response.addFieldError(new ApiFieldError("REQUIRED_NOT_NULL", "name", "must not be null", null, "name"));
response.addErrorProperty("requestId", "abc-123");
```

--------------------------------

### RequestIdCustomizer example implementation

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/exception-handler-spi.md

Example implementation of ApiErrorResponseCustomizer that adds a requestId property to the response. Uses RequestContextHolder to get the session ID, handling null request attributes.

```java
@Component
public class RequestIdCustomizer implements ApiErrorResponseCustomizer {
    @Override
    public void customize(ApiErrorResponse response) {
        response.addErrorProperty("requestId", RequestContextHolder.getRequestAttributes() == null
            ? null : RequestContextHolder.currentRequestAttributes().getSessionId());
    }
}
```

--------------------------------

### Example JSON error response

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-validation.md

Example JSON response for a validation failure with field and parameter errors.

```json
{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed. Error count: 2",
  "fieldErrors": [
    {"code": "REQUIRED_NOT_NULL", "message": "must not be null", "property": "id", "rejectedValue": null, "path": "id"}
  ],
  "parameterErrors": [
    {"code": "VALUE_LESS_THAN_MIN", "message": "must be greater than or equal to 1", "parameter": "id", "rejectedValue": 0}
  ]
}
```

--------------------------------

### Example usage of HttpStatusMapper in a custom handler

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/mappers.md

Shows how to call getHttpStatus with a custom default status of BAD_REQUEST.

```java
HttpStatusCode status = httpStatusMapper.getHttpStatus(ex, HttpStatus.BAD_REQUEST);
```

--------------------------------

### Example response for optimistic locking error

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-framework.md

Example JSON response with code OPTIMISTIC_LOCKING_ERROR, message, identifier, and persistentClassName. Status is 409 by default.

```json
{
  "code": "OPTIMISTIC_LOCKING_ERROR",
  "message": "Object of class [Todo] with identifier [42]: optimistic locking failed...",
  "identifier": 42,
  "persistentClassName": "Todo"
}
```

--------------------------------

### @ResponseErrorProperty usage example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/default-fallback-api-exception-handler.md

Example exception using both attributes: default property name for todoId, explicit name "requestedAt" for the field, and includeIfNull=true for the getOwner method. Methods must be no-arg and non-void.

```java
@ResponseErrorCode("TODO_NOT_FOUND")
public class TodoNotFoundException extends RuntimeException {
    @ResponseErrorProperty
    private final long todoId;

    @ResponseErrorProperty("requestedAt")
    private final Instant requestedAt;

    @ResponseErrorProperty(includeIfNull = true)
    public String getOwner() { return null; }

    public TodoNotFoundException(long todoId, Instant requestedAt) {
        this.todoId = todoId;
        this.requestedAt = requestedAt;
    }
}
```

--------------------------------

### Example JSON response with custom field names

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Shows the JSON response structure after applying the custom field names. Includes fieldFailures and classFailures arrays with error details.

```json
{
  "errorCode": "VALIDATION_FAILED",
  "description": "Validation failed for object='exampleRequestBody'. Error count: 4",
  "fieldFailures": [
    {
      "code": "INVALID_SIZE",
      "property": "name",
      "message": "size must be between 10 and 2147483647",
      "rejectedValue": "",
      "path": "name"
    }
  ],
  "classFailures": [
    {
      "code": "ValidCustomer",
      "message": "UserAlreadyExists"
    }
  ]
}
```

--------------------------------

### Problem Detail error response (enabled)

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example of the error response when Problem Detail format is enabled. Contains type, title, status, and detail fields.

```json
{
  "type": "user-not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Could not find user with id 123"
}
```

--------------------------------

### Custom UserNotFoundException example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

A custom exception that the library will handle by default, returning a JSON response with a code and message derived from the exception name and message.

```java
package com.company.application.user;

public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(UserId userId) {
        super("Could not find user with id " + userId);
    }
}
```

--------------------------------

### Example JSON error response for reactive controller

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/reactive.md

Example response body produced when a reactive controller throws an exception. `type` is the kebab-cased error code prefixed by `problemDetailTypePrefix`; `fieldErrors`/`globalErrors` are only included when non-empty.

```json
{
  "type": "todo-not-found",
  "status": 404,
  "detail": "Todo 42 not found",
  "todoId": 42
}
```

--------------------------------

### Response for @ResponseErrorCode example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Shows the JSON response when using the @ResponseErrorCode annotation.

```json
{
  "code": "COULD_NOT_FIND_USER",
  "message": "Could not find user with id 123"
}

```

--------------------------------

### ClientErrorLoggingFilter example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/logging.md

Example filter that suppresses logging for expected 4xx client errors. Declaring this bean is enough; the auto-configured LoggingService injects the only LoggingServiceFilter bean.

```java
@Component
public class ClientErrorLoggingFilter implements LoggingServiceFilter {
    @Override
    public boolean shouldLogException(ApiErrorResponse errorResponse, Throwable exception) {
        return errorResponse.getHttpStatus() == null
            || !errorResponse.getHttpStatus().is4xxClientError();
    }
}
```

--------------------------------

### Customizing every response with ApiErrorResponseCustomizer

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/error-handling-facade.md

Example of a customizer that adds a traceId property to every ApiErrorResponse using MDC.

```java
@Component
public class TraceIdCustomizer implements ApiErrorResponseCustomizer {
    @Override
    public void customize(ApiErrorResponse response) {
        response.addErrorProperty("traceId", MDC.get("traceId"));
    }
}
```

--------------------------------

### Example 401 response body

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/security.md

Shows the JSON structure returned when authentication fails, with a code of UNAUTHORIZED and a message indicating full authentication is required.

```json
{
  "code": "UNAUTHORIZED",
  "message": "Full authentication is required to access this resource"
}
```

--------------------------------

### JSON response from custom exception handler

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example JSON response produced by the custom exception handler, showing the added cause property with code and message.

```json
{
  "code": "MY_CUSTOM_EXCEPTION",
  "message": "parent exception message",
  "cause": {
    "code": "CAUSE",
    "message": "child IOException message"
  }
}
```

--------------------------------

### Example request and response for malformed JSON

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-web.md

Shows a POST /todos request with invalid JSON body and the resulting JSON response with code MESSAGE_NOT_READABLE and a parse error message.

```java
// POST /todos with body "{invalid json"
```

```json
{
  "code": "MESSAGE_NOT_READABLE",
  "message": "JSON parse error: Unexpected character..."
}
```

--------------------------------

### Validation errors in Problem Detail response

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example of a Problem Detail response for validation errors, including fieldErrors and globalErrors arrays with details about each failed validation.

```json
{
  "type": "validation-failed",
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation failed for object='exampleRequestBody'. Error count: 2",
  "fieldErrors": [
    {
      "code": "INVALID_SIZE",
      "property": "name",
      "message": "size must be between 10 and 2147483647",
      "rejectedValue": "",
      "path": "name"
    },
    {
      "code": "REQUIRED_NOT_BLANK",
      "property": "favoriteMovie",
      "message": "must not be blank",
      "rejectedValue": null,
      "path": "favoriteMovie"
    }
  ]
}
```

--------------------------------

### Customize JSON field names with error.handling.json-field-names properties

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Sets custom JSON field names for error responses. The example maps 'code' to 'errorCode', 'message' to 'description', 'field-errors' to 'fieldFailures', and 'global-errors' to 'classFailures'.

```properties
error.handling.json-field-names.code=errorCode
error.handling.json-field-names.message=description
error.handling.json-field-names.field-errors=fieldFailures
error.handling.json-field-names.global-errors=classFailures
```

--------------------------------

### Maven dependency for error-handling-spring-boot-starter

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Add the library to your Maven project. Replace LATEST_VERSION_HERE with the current version from Maven Central.

```xml
<dependency>
    <groupId>io.github.wimdeblauwe</groupId>
    <artifactId>error-handling-spring-boot-starter</artifactId>
    <version>LATEST_VERSION_HERE</version>
</dependency>
```

--------------------------------

### YAML configuration for reactive error handling

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/reactive.md

Configuration for the WebFlux starter. `error.handling.enabled` (default `true`) toggles the whole stack; `use-problem-detail-format` enables RFC 7807 responses.

```yaml
error:
  handling:
    enabled: true
    use-problem-detail-format: true   # RFC 7807 responses
```

--------------------------------

### Gradle dependency for error-handling-spring-boot-starter

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Add the library to your Gradle project. Replace LATEST_VERSION_HERE with the current version from Maven Central.

```groovy
compile 'io.github.wimdeblauwe:error-handling-spring-boot-starter:LATEST_VERSION_HERE'
```

--------------------------------

### Configuration Properties

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Configuration properties for the error handling starter. These properties allow enabling/disabling error handling, setting exception logging behavior, and specifying classes or HTTP statuses that always print a stack trace.

```APIDOC
## Configuration Properties

### Description
Properties to configure the error handling starter.

### Properties

#### error.handling.enabled
- **Type**: boolean
- **Default**: `true`
- **Description**: Allows to enable or disable the error handling.

#### error.handling.exception-logging
- **Type**: enum (NO_LOGGING, MESSAGE_ONLY, WITH_STACKTRACE)
- **Default**: `MESSAGE_ONLY`
- **Description**: Allows to set how the exception should be logged.

#### error.handling.full-stacktrace-classes
- **Type**: list of fully qualified class names
- **Default**: (empty)
- **Description**: Specifies a list of Exception classes that will always print a stack trace in the logging, regardless of the `error.handling.exception-logging` setting.

#### error.handling.full-stacktrace-http-statuses
- **Type**: list of HTTP error codes or ranges
- **Default**: (empty)
- **Description**: Specifies a list of HTTP error codes (or ranges) that will always print a stack trace in the logging, regardless of the `error.handling.exception-logging` setting. A fixed code like `500` or a range like `50x` or `5xx` is possible.
```

--------------------------------

### @ResponseErrorCode usage example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/default-fallback-api-exception-handler.md

Example of annotating an exception class with @ResponseErrorCode("TODO_NOT_FOUND"). The error code is used in the JSON response.

```java
@ResponseErrorCode("TODO_NOT_FOUND")
public class TodoNotFoundException extends RuntimeException {
    // ...
}
```

--------------------------------

### Manual construction and usage of ErrorHandlingFacade

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/error-handling-facade.md

Shows how to manually construct an ErrorHandlingFacade with a custom handler and fallback, then handle a business exception.

```java
List<ApiExceptionHandler> handlers = List.of(new MyCustomHandler(httpStatusMapper, errorCodeMapper, errorMessageMapper));
FallbackApiExceptionHandler fallback = new DefaultFallbackApiExceptionHandler(httpStatusMapper, errorCodeMapper, errorMessageMapper);

ErrorHandlingFacade facade = new ErrorHandlingFacade(
    handlers, fallback, new LoggingService(properties, new AlwaysLogLoggingServiceFilter()), List.of()
);

ApiErrorResponse response = facade.handle(new MyBusinessException());
```

--------------------------------

### application.yml configuration for exception logging

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/logging.md

Configuration for full-stacktrace logging for selected classes and HTTP statuses, and log levels. Default exception-logging is message-only.

```yaml
error:
  handling:
    exception-logging: message-only        # default
    full-stacktrace-classes:
      - com.example.MyCriticalException
    full-stacktrace-http-statuses:
      - "5xx"                              # wildcard: stacktrace for any 5xx
    log-levels:
      "400": warn                          # 4xx at WARN, everything else ERROR
```

--------------------------------

### Custom exception handler implementation example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example implementation of ApiExceptionHandler that adds the first-level cause of an exception to the error response. Annotate with @Component to register it in the Spring context. Uses addErrorProperty to add custom fields.

```java
package io.github.wimdeblauwe.errorhandlingspringbootstarter.handler;

import io.github.wimdeblauwe.errorhandlingspringbootstarter.ApiErrorResponse;
import io.github.wimdeblauwe.errorhandlingspringbootstarter.ApiExceptionHandler;
import org.jspecify.annotations.Nullable;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;

import java.util.HashMap;
import java.util.Map;
import java.util.Objects;

@Component //<.>
public class CustomExceptionApiExceptionHandler implements ApiExceptionHandler { //<.>
    @Override
    public boolean canHandle(Throwable exception) {
        return exception instanceof CustomException; //<.>
    }

    @Override
    public ApiErrorResponse handle(Throwable exception) {
        CustomException customException = (CustomException) exception;

        ApiErrorResponse response = new ApiErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR, //<.>
                                                         "MY_CUSTOM_EXCEPTION",
                                                         Objects.requireNonNull(exception.getMessage()));
        Throwable cause = customException.getCause();
        Objects.requireNonNull(cause);
        Map<String, Object> nestedCause = new HashMap<>();
        nestedCause.put("code", "CAUSE");
        nestedCause.put("message", Objects.requireNonNull(cause.getMessage()));
        response.addErrorProperty("cause", nestedCause); //<.>

        return response;
    }
}
```

--------------------------------

### Configure settings for RuntimeException subclasses

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Sets HTTP status, error code, and message for any RuntimeException subclass using the superclass hierarchy search.

```properties
error.handling.http-statuses.java.lang.RuntimeException=bad_request
error.handling.codes.java.lang.RuntimeException=RUNTIME_EXCEPTION
error.handling.messages.java.lang.RuntimeException=A runtime exception has happened
```

--------------------------------

### Configure exception logging and full stacktrace classes

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Sets exception-logging to MESSAGE_ONLY and specifies classes that should have full stack traces. Only exact class matches are used, not subclasses.

```properties
error.handling.exception-logging=MESSAGE_ONLY
error.handling.full-stacktrace-classes[0]=java.lang.NullPointerException
error.handling.full-stacktrace-classes[1]=org.springframework.http.converter.HttpMessageNotReadableException
```

--------------------------------

### Resulting JSON for a 404 response

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/default-fallback-api-exception-handler.md

JSON output for the TodoNotFoundException example. The status field only appears when error.handling.http-status-in-json-response=true.

```json
{
  "status": 404,
  "code": "TODO_NOT_FOUND",
  "message": "Todo 42 not found",
  "todoId": 42,
  "requestedAt": "2024-01-01T10:00:00Z",
  "owner": null
}
```

--------------------------------

### Configure Problem Detail type prefix

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Set the property error.handling.problem-detail-type-prefix to add a prefix to the type field, creating fully qualified URIs for documentation links.

```properties
error.handling.use-problem-detail-format=true
error.handling.problem-detail-type-prefix=https://api.example.com/errors/
```

--------------------------------

### Serialized JSON output

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/api-error-response.md

The JSON produced by the serializer from the previous example. Shows the code, message, fieldErrors, and requestId fields.

```json
{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed",
  "fieldErrors": [{"code": "REQUIRED_NOT_NULL", "message": "must not be null", "property": "name", "rejectedValue": null, "path": "name"}],
  "requestId": "abc-123"
}
```

--------------------------------

### Response for RuntimeException subclass with superclass settings

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Response JSON showing the configured code and message for a RuntimeException subclass when superclass hierarchy search is enabled.

```json
{
  "code": "RUNTIME_EXCEPTION",
  "message": "A runtime exception has happened"
}
```

--------------------------------

### Example validation error response

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/handlers-validation.md

JSON response for a validation failure on the createTodoRequest object, with field error for missing name.

```json
{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed for object='createTodoRequest'. Error count: 1",
  "fieldErrors": [
    {"code": "REQUIRED_NOT_NULL", "message": "must not be null", "property": "name", "rejectedValue": null, "path": "name"}
  ]
}
```

--------------------------------

### Validation Failed Response with Global Errors

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example JSON response for a validation failure, showing the globalErrors array with codes and messages.

```json
{
  "code": "VALIDATION_FAILED",
  "message": "Validation failed for object='exampleRequestBody'. Error count: 2",
  "globalErrors": [
    {
      "code": "INVALID_CUSTOMER",
      "message": "Invalid customer"
    },
    {
      "code": "INVALID_CUSTOMER",
      "message": "The user already exists"
    }
  ]
}
```

--------------------------------

### Invalid JSON request body for validation example

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

A JSON request body that fails validation because name is empty and favoriteMovie is null.

```json
{
    "name": "",
    "favoriteMovie": null
}
```

--------------------------------

### LoggingService constructor

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/logging.md

Constructor that takes ErrorHandlingProperties and LoggingServiceFilter. Both parameters are required.

```java
public LoggingService(ErrorHandlingProperties properties,
                      LoggingServiceFilter loggingServiceFilter)
```

--------------------------------

### ErrorMessageMapper class declaration

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/mappers.md

The class contains the logic for getting the matching error message for a given Throwable. It holds an ErrorHandlingProperties instance.

```java
/**
 * This class contains the logic for getting the matching error message for the given {@link Throwable}.
 */
public class ErrorMessageMapper {
    private final ErrorHandlingProperties properties;
}
```

--------------------------------

### ExampleRequestBody with validation annotations

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

A request body class with validation constraints. Used to demonstrate validation exception handling.

```java
public class ExampleRequestBody {
    @Size(min = 10)
    private String name;
    @NotBlank
    private String favoriteMovie;

    // getters and setters
}
```

--------------------------------

### ErrorCodeMapper class definition

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/mappers.md

The ErrorCodeMapper class contains the logic for getting the matching error code for a given Throwable. It holds an ErrorHandlingProperties instance.

```java
/**
 * This class contains the logic for getting the matching error code for the given {@link Throwable}.
 */
public class ErrorCodeMapper {
    private final ErrorHandlingProperties properties;
}
```

--------------------------------

### Configure full stacktrace for HTTP statuses

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Specifies HTTP status codes for which full stack traces should be printed. This is additional to exception-type-based logging, so enabling both may cause double stack traces.

```properties
error.handling.full-stacktrace-http-statuses[0]=5xx
error.handling.full-stacktrace-http-statuses[1]=403
```

--------------------------------

### Problem Detail response with original error code

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example response when kebab-case conversion is disabled. The type field retains the original error code.

```json
{
  "type": "USER_NOT_FOUND",
  "title": "Not Found",
  "status": 404,
  "detail": "Could not find user with id 123"
}
```

--------------------------------

### UnauthorizedEntryPoint commence method signature

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/security.md

Method signature for commence, handling authentication failures by writing the error response.

```java
@Override
public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException authException) throws IOException
```

--------------------------------

### ProblemDetailFactory constructor

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/problem-detail-factory.md

Constructor that takes ErrorHandlingProperties, which supplies problemDetailTypePrefix and problemDetailConvertToKebabCase.

```java
public ProblemDetailFactory(ErrorHandlingProperties properties)
```

--------------------------------

### Enable filter-chain handling in application.yml

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/servlet.md

Configuration to enable the filter-chain exception handling. Requires error.handling.enabled=true and error.handling.handle-filter-chain-exceptions=true.

```yaml
error:
  handling:
    enabled: true
    handle-filter-chain-exceptions: true
```

--------------------------------

### Custom exception with @ResponseErrorProperty

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example of a custom exception class using @ResponseStatus, @ResponseErrorCode, and @ResponseErrorProperty annotations to include custom properties in the Problem Detail response.

```java
@ResponseStatus(HttpStatus.CONFLICT)
@ResponseErrorCode("OPTIMISTIC_LOCKING_ERROR")
public class OptimisticLockingException extends RuntimeException {

    @ResponseErrorProperty
    private final String identifier;

    @ResponseErrorProperty
    private final String persistentClassName;

    // constructor and getters
}
```

--------------------------------

### Logging Configuration

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/logging.md

Configuration options for exception logging via application.yml, including log levels, full stacktrace classes, and HTTP statuses.

```APIDOC
## Logging Configuration

### Description
Configuration properties for controlling exception logging behavior.

### Configuration Properties
- **error.handling.exception-logging** (string) - Optional - Default: `message-only`. Determines the logging mode.
- **error.handling.full-stacktrace-classes** (list of strings) - Optional - List of exception class names for which full stacktrace should be logged.
- **error.handling.full-stacktrace-http-statuses** (list of strings) - Optional - List of HTTP statuses (e.g., `5xx`) for which full stacktrace should be logged.
- **error.handling.log-levels** (map) - Optional - Mapping of HTTP status codes to log levels (e.g., `400: warn`).

### Example
```yaml
error:
  handling:
    exception-logging: message-only        # default
    full-stacktrace-classes:
      - com.example.MyCriticalException
    full-stacktrace-http-statuses:
      - "5xx"                              # wildcard: stacktrace for any 5xx
    log-levels:
      "400": warn                          # 4xx at WARN, everything else ERROR
```
```

--------------------------------

### ProblemDetailFactory build method

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/problem-detail-factory.md

Builds a ProblemDetail from an ApiErrorResponse. Throws NullPointerException if httpStatus is null. The type URI is built using the prefix and kebab-case conversion.

```java
public ProblemDetail build(ApiErrorResponse errorResponse)
```

--------------------------------

### Enable Problem Detail format property

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Set this property to true to enable the RFC 9457 Problem Detail format for error responses, using the application/problem+json content type.

```properties
error.handling.use-problem-detail-format=true
```

--------------------------------

### Java class with @Pattern validation annotation

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example Java class with a @Pattern annotation on the password field, used to demonstrate field-specific error message overrides.

```java
public class CreateUserRequestBody {
    @Pattern(".*{8}")
    private String password;

    // getters and setters
}
```

--------------------------------

### ServletProblemDetailResponseFactory implementation

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/servlet.md

Package-private implementation that builds a ProblemDetail via ProblemDetailFactory and returns an RFC 7807 response with application/problem+json content type.

```java
class ServletProblemDetailResponseFactory implements ServletResponseFactory {

    private final ProblemDetailFactory problemDetailFactory;
    ...
    @Override
    public ResponseEntity<?> create(ApiErrorResponse errorResponse) {
        ProblemDetail problemDetail = problemDetailFactory.build(errorResponse);
        return ResponseEntity.status(Objects.requireNonNull(errorResponse.getHttpStatus()))
                             .contentType(MediaType.APPLICATION_PROBLEM_JSON)
                             .body(problemDetail);
    }
}
```

--------------------------------

### Custom ApiExceptionHandler for TodoNotFoundException

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/exception-handler-spi.md

Example handler that responds with HTTP 404 and error code TODO_NOT_FOUND. Uses @Order(Ordered.HIGHEST_PRECEDENCE) to control precedence among handlers.

```java
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class TodoNotFoundExceptionHandler implements ApiExceptionHandler {
    @Override
    public boolean canHandle(Throwable exception) {
        return exception instanceof TodoNotFoundException;
    }

    @Override
    public ApiErrorResponse handle(Throwable exception) {
        TodoNotFoundException ex = (TodoNotFoundException) exception;
        return new ApiErrorResponse(HttpStatus.NOT_FOUND, "TODO_NOT_FOUND", ex.getMessage());
    }
}
```

--------------------------------

### ApiGlobalError Constructor

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/api-error-response.md

Creates an ApiGlobalError instance with the given code and message.

```APIDOC
## ApiGlobalError Constructor

### Description
Creates an ApiGlobalError instance with the given code and message.

### Method
Constructor

### Signature
`public ApiGlobalError(String code, String message)`

### Parameters
- **code** (`String`) - Required - Global error code (e.g. object-level validation).
- **message** (`String`) - Required - Human-readable message.

```

--------------------------------

### Get the response from the exception instance - resulting JSON

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

When a MethodNotAllowedException is thrown, the library automatically uses the response status from the exception instance. This is the resulting JSON response.

```json
{
  "code": "METHOD_NOT_ALLOWED",
  "message": "405 METHOD_NOT_ALLOWED \"Request method 'OPTIONS' not supported\""
}
```

--------------------------------

### ErrorHandlingControllerAdvice constructor signature

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/servlet.md

Constructor that takes the ErrorHandlingFacade and ServletResponseFactory. Both parameters are required.

```java
public ErrorHandlingControllerAdvice(ErrorHandlingFacade errorHandlingFacade, ServletResponseFactory responseFactory)
```

--------------------------------

### JSON error response for optimistic locking

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Example JSON response for an optimistic locking error, showing the structure with type, title, status, detail, identifier, and persistentClassName fields.

```json
{
  "type": "https://api.example.com/errors/optimistic-locking-error",
  "title": "Conflict",
  "status": 409,
  "detail": "Object of class [com.example.user.User] with identifier [1]: optimistic locking failed",
  "identifier": "1",
  "persistentClassName": "com.example.user.User"
}
```

--------------------------------

### Enable super class hierarchy search

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Enables the `error.handling.search-super-class-hierarchy` setting to allow settings for exception superclasses.

```properties
error.handling.search-super-class-hierarchy=true
```

--------------------------------

### Global customization with ApiErrorResponseCustomizer bean

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/src/docs/asciidoc/index.adoc

Implement ApiErrorResponseCustomizer to add properties globally to all error responses, including those from libraries. The example adds a timestamp property. Multiple such beans can be declared.

```java
    @Bean
    public ApiErrorResponseCustomizer timestampErrorResponseCustomizer() {
        return new ApiErrorResponseCustomizer() {
            @Override
            public void customize(ApiErrorResponse response) {
                response.addErrorProperty("instant", Instant.now());
            }
        };
    }
```

```json
{
  "code": "USER_NOT_FOUND",
  "message": "Could not find user with id UserId{id=8c7fb13c-0924-47d4-821a-36f73558c898}",
  "instant": "2023-06-14T06:20:12.719357Z"
}
```

--------------------------------

### ErrorHandlingFacade Constructor

Source: https://github.com/wimdeblauwe/error-handling-spring-boot-starter/blob/develop/_autodocs/api-reference/error-handling-facade.md

Creates an ErrorHandlingFacade with the given handlers, fallback handler, logging service, and response customizers. The handlers list should be ordered, and the auto-configuration sorts it with AnnotationAwareOrderComparator.INSTANCE.

```APIDOC
## ErrorHandlingFacade Constructor

### Description
Creates an ErrorHandlingFacade instance with the provided dependencies.

### Signature
```java
public ErrorHandlingFacade(List<ApiExceptionHandler> handlers, FallbackApiExceptionHandler fallbackHandler, LoggingService loggingService,
                           List<ApiErrorResponseCustomizer> responseCustomizers)
```

### Parameters
- **handlers** (List<ApiExceptionHandler>) - Required - Ordered list of candidate handlers. The auto-configuration sorts it with `AnnotationAwareOrderComparator.INSTANCE` before constructing the facade.
- **fallbackHandler** (FallbackApiExceptionHandler) - Required - Handler invoked when no `ApiExceptionHandler` claims the exception.
- **loggingService** (LoggingService) - Required - Performs logging after a response is built.
- **responseCustomizers** (List<ApiErrorResponseCustomizer>) - Required - Applied to every response in declaration order.

### Example
```java
List<ApiExceptionHandler> handlers = List.of(new MyCustomHandler(httpStatusMapper, errorCodeMapper, errorMessageMapper));
FallbackApiExceptionHandler fallback = new DefaultFallbackApiExceptionHandler(httpStatusMapper, errorCodeMapper, errorMessageMapper);

ErrorHandlingFacade facade = new ErrorHandlingFacade(
    handlers, fallback, new LoggingService(properties, new AlwaysLogLoggingServiceFilter()), List.of()
);
```
```
Tokens:
Raw