Zalando Problem

https://github.com/zalando/problem
Admin
Zalando Problem is a Java library that implements application/problem+json, proposing a common...
Tokens:30,446
Snippets:427
Trust Score:8.3
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Configure Gson with ProblemAdapterFactory

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Basic setup for registering the ProblemAdapterFactory with a GsonBuilder.

```java
Gson gson = new GsonBuilder()
    .registerTypeAdapterFactory(new ProblemAdapterFactory())
    .create();
```

```java
Gson gson = new GsonBuilder()
    .registerTypeAdapterFactory(new ProblemAdapterFactory().withStackTraces())
    .create();
```

```java
Gson gson = new GsonBuilder()
    .registerTypeAdapterFactory(new ProblemAdapterFactory(CustomStatus.class))
    .create();
```

```java
Gson gson = new GsonBuilder()
    .registerTypeAdapterFactory(
        new ProblemAdapterFactory(Status.class, CustomStatus.class)
    )
    .create();
```

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

### Construct ThrowableProblem with ProblemBuilder

Source: https://github.com/zalando/problem/blob/main/_autodocs/types.md

Example of using the ProblemBuilder to set various fields and custom parameters for a problem instance.

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/validation-error"))
    .withTitle("Validation Error")
    .withStatus(Status.UNPROCESSABLE_ENTITY)
    .withDetail("Email field is invalid")
    .with("field", "email")
    .with("value", "invalid@")
    .build();
```

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

### JSON Representation of a Problem with Stack Trace

Source: https://github.com/zalando/problem/blob/main/README.md

Example JSON output showing the stacktrace property.

```json
{
  "type": "about:blank",
  "title": "Unprocessable Entity",
  "status": 400,
  "stacktrace": [
    "org.example.Example.execute(Example.java:17)",
    "org.example.Example.main(Example.java:11)"
  ]
}
```

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

### Implement getCause in Exceptional

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Exceptional.md

Provides an implementation example of the getCause method for an exception class implementing the Exceptional interface.

```java
public class OutOfStockException extends BusinessException implements Exceptional {
    private final Exceptional cause;

    public OutOfStockException(String product, Exceptional cause) {
        super("Product out of stock: " + product);
        this.cause = cause;
    }

    @Override
    public Exceptional getCause() {
        return cause;
    }
}

// Usage
OutOfStockException cause = new OutOfStockException("B00027Y5QG", null);
OutOfStockException problem = new OutOfStockException("B00027Y5QG", cause);
assert problem.getCause() != null;
```

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

### Get string representation

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Status.md

Returns a string formatted as '{statusCode} {reasonPhrase}'.

```java
public String toString()
```

```java
String str = Status.NOT_FOUND.toString();
// Returns: "404 Not Found"
```

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

### Define a Custom Problem Class

Source: https://github.com/zalando/problem/blob/main/README.md

Example of annotating a custom problem class with type information and a creator.

```java
@JsonTypeName(OutOfStockProblem.TYPE_VALUE)
public final class OutOfStockProblem implements Problem {

    @JsonCreator
    public OutOfStockProblem(final String product) {
```

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

### Get ThrowableProblem Message

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ThrowableProblem.md

Retrieves a combined string of the problem title and detail.

```java
public String getMessage()
```

```java
ThrowableProblem problem = Problem.valueOf(
    Status.NOT_FOUND, 
    "Order 123 not found"
);
String message = problem.getMessage();
// Returns: "Not Found: Order 123 not found"
```

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

### Create Simple Problems in Java

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Demonstrates creating basic ThrowableProblem instances from HTTP statuses and throwing them as exceptions.

```java
// Create from HTTP status
ThrowableProblem problem = Problem.valueOf(Status.NOT_FOUND);

// Create with detail
ThrowableProblem problem = Problem.valueOf(
    Status.NOT_FOUND, 
    "User 123 not found"
);

// Throw as exception
throw problem;
```

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

### Creating and Accessing a Problem Instance

Source: https://github.com/zalando/problem/blob/main/_autodocs/types.md

Demonstrates building a Problem instance and accessing its properties.

```java
Problem problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(Status.BAD_REQUEST)
    .withDetail("Item B00027Y5QG is unavailable")
    .build();

URI type = problem.getType();           // https://example.org/out-of-stock
String title = problem.getTitle();      // "Out of Stock"
StatusType status = problem.getStatus(); // Status.BAD_REQUEST
String detail = problem.getDetail();    // "Item B00027Y5QG is unavailable"
```

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

### Get ThrowableProblem Cause

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ThrowableProblem.md

Provides type-safe access to the causal problem.

```java
public ThrowableProblem getCause()
```

```java
ThrowableProblem outOfStock = Problem.builder()
    .withTitle("Out of Stock")
    .withStatus(Status.BAD_REQUEST)
    .build();

ThrowableProblem orderFailed = Problem.builder()
    .withTitle("Order Failed")
    .withStatus(Status.BAD_REQUEST)
    .withCause(outOfStock)
    .build();

ThrowableProblem cause = orderFailed.getCause();
// Returns: outOfStock
```

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

### Implementing a custom ThrowableProblem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ThrowableProblem.md

Shows how to instantiate a custom ThrowableProblem, which automatically captures the stack trace at construction time.

```java
throw new ThrowableProblem() {
    @Override
    public URI getType() { return URI.create("https://example.org/error"); }
    @Override
    public String getTitle() { return "Error"; }
    @Override
    public StatusType getStatus() { return Status.INTERNAL_SERVER_ERROR; }
};
// Stack trace is captured at construction time
```

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

### Create DefaultProblem via Builder

Source: https://github.com/zalando/problem/blob/main/_autodocs/types.md

Demonstrates the standard way to instantiate a DefaultProblem using the Problem.builder() fluent API.

```java
// Create DefaultProblem via builder
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/problem"))
    .withStatus(Status.BAD_REQUEST)
    .with("field", "value")
    .build();  // Returns DefaultProblem instance

assert problem instanceof DefaultProblem;
```

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

### Create Problem with Status, Detail, and URI

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Creates a comprehensive problem instance including status code, detail message, and instance URI.

```java
static ThrowableProblem valueOf(final StatusType status, 
                                @Nullable final String detail, 
                                @Nullable final URI instance)
```

```java
Problem problem = Problem.valueOf(
    Status.NOT_FOUND, 
    "Order 123 not found", 
    URI.create("https://example.org/orders/123")
);
```

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

### Register Custom Problem Subtypes

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Example of registering multiple custom problem subclasses for polymorphic deserialization.

```java
Gson gson = new GsonBuilder()
    .registerTypeAdapterFactory(
        new ProblemAdapterFactory()
            .registerSubtype(
                URI.create("https://example.org/out-of-stock"),
                OutOfStockProblem.class
            )
            .registerSubtype(
                URI.create("https://example.org/insufficient-funds"),
                InsufficientFundsProblem.class
            )
    )
    .create();
```

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

### Initialize AbstractThrowableProblem with type, title, status, detail, and instance

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance specifying the problem type, title, status, detail, and instance URI.

```java
protected AbstractThrowableProblem(@Nullable final URI type, 
                                  @Nullable final String title, 
                                  @Nullable final StatusType status, 
                                  @Nullable final String detail, 
                                  @Nullable final URI instance)
```

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

### Create a Basic Problem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

Construct a minimal problem instance using the builder pattern.

```java
// Minimal problem
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.BAD_REQUEST)
    .build();

assert problem.getStatus().getStatusCode() == 400;
assert problem.getType().equals(URI.create("about:blank"));
```

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

### Retrieve Problem Detail

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Demonstrates retrieving the problem detail explanation using getDetail().

```java
public String getDetail()
```

```java
public class OutOfStockProblem extends AbstractThrowableProblem {
    private final String product;

    public OutOfStockProblem(String product) {
        super(
            URI.create("https://example.org/out-of-stock"),
            "Out of Stock",
            Status.BAD_REQUEST,
            String.format("Item %s is no longer available", product)
        );
        this.product = product;
    }

    public String getProduct() {
        return product;
    }
}

OutOfStockProblem problem = new OutOfStockProblem("B00027Y5QG");
assert problem.getDetail().equals("Item B00027Y5QG is no longer available");
```

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

### Create Problems from Status

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Status.md

Demonstrates creating ThrowableProblem instances using predefined Status constants or the builder pattern.

```java
// Simple problem from status
ThrowableProblem problem = Problem.valueOf(Status.NOT_FOUND);

// Problem with detail
ThrowableProblem problem = Problem.valueOf(
    Status.SERVICE_UNAVAILABLE, 
    "Database connection failed"
);

// Using with builder
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.UNPROCESSABLE_ENTITY)
    .withTitle("Validation Error")
    .build();
```

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

### Demonstrate Immutability with ProblemModule

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Builder methods return new instances, ensuring that original configurations remain unchanged.

```java
ProblemModule module1 = new ProblemModule();
ProblemModule module2 = module1.withStackTraces();  // New instance

assert module1 != module2;  // Different objects
assert !module1.equals(module2);  // Different configurations
```

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

### Create a Complete Problem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

Construct a fully defined problem with type, title, status, detail, instance, and custom parameters.

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://api.example.org/problems/validation-error"))
    .withTitle("Validation Error")
    .withStatus(Status.UNPROCESSABLE_ENTITY)
    .withDetail("Email field contains invalid format")
    .withInstance(URI.create("https://api.example.org/validation/123"))
    .with("field", "email")
    .with("pattern", "[a-z]+@[a-z]+\\.[a-z]+")
    .build();
```

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

### Initialize AbstractThrowableProblem with type, title, status, and detail

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance specifying the problem type, title, status, and a detailed explanation.

```java
protected AbstractThrowableProblem(@Nullable final URI type, 
                                  @Nullable final String title, 
                                  @Nullable final StatusType status, 
                                  @Nullable final String detail)
```

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

### Initialize ProblemBuilder

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Create a new instance of the builder using the static factory method.

```java
ProblemBuilder builder = Problem.builder();
```

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

### ProblemModule()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Initializes the ProblemModule with standard HTTP status mappings.

```APIDOC
## ProblemModule()

### Description
Default constructor that initializes the module using the standard HTTP Status enum for status code mapping.

### Signature
`public ProblemModule()`

### Example
```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule())
    .build();
```
```

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

### Configure JPMS module-info.java

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Include these requirements in your module-info.java file to enable the library and its Jackson support.

```java
module my.app {
    requires org.zalando.problem;
    requires org.zalando.problem.jackson;
}
```

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

### Initialize AbstractThrowableProblem with type and title

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance specifying the problem type URI and a human-readable title.

```java
protected AbstractThrowableProblem(@Nullable final URI type, 
                                  @Nullable final String title)
```

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

### Constructing a DefaultProblem instance

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

Instances must be created using the Problem builder pattern as constructors are package-private.

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/problem"))
    .withStatus(Status.BAD_REQUEST)
    .build();

assert problem instanceof DefaultProblem;
```

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

### Handling Exceptions with ThrowableProblem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ThrowableProblem.md

Demonstrates catching specific problem types and a fallback to ThrowableProblem.

```java
try {
    processPayment();
} catch (OutOfStockProblem e) {
    tellCustomerProductIsNoLongerAvailable(e.getProduct());
} catch (InsufficientFundsProblem e) {
    askCustomerToUseDifferentPaymentMethod(e.getBalance(), e.getDebit());
} catch (ThrowableProblem e) {
    tellCustomerSomethingWentWrong();
}
```

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

### build()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Constructs the final ThrowableProblem instance from the configured builder.

```APIDOC
## build()

### Description
Constructs the final `ThrowableProblem` instance. Creates an immutable `DefaultProblem` with all properties set via the builder methods.

### Signature
`public ThrowableProblem build()`

### Returns
- **ThrowableProblem** - The constructed problem instance.
```

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

### Build a Problem instance

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Construct a ThrowableProblem using the fluent builder API.

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(Status.BAD_REQUEST)
    .withDetail("Item B00027Y5QG is no longer available")
    .withInstance(URI.create("https://api.example.org/orders/123"))
    .with("product_id", "B00027Y5QG")
    .with("requested_quantity", 5)
    .build();
```

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

### Problem Factory and Builder

Source: https://github.com/zalando/problem/blob/main/_autodocs/types.md

Static methods for creating Problem instances.

```APIDOC
## Problem Factory and Builder

### Description
Static methods to instantiate Problem objects, including a builder pattern and convenience factory methods.

### Methods
- **builder()** (ProblemBuilder) - Returns a new builder instance for constructing a Problem.
- **valueOf(StatusType)** (ThrowableProblem) - Creates a problem from a status.
- **valueOf(StatusType, String)** (ThrowableProblem) - Creates a problem from a status and detail message.
- **valueOf(StatusType, URI)** (ThrowableProblem) - Creates a problem from a status and type URI.
- **valueOf(StatusType, String, URI)** (ThrowableProblem) - Creates a problem from a status, detail message, and type URI.
- **toString(Problem)** (String) - Returns a string representation of the problem.
```

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

### builder()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Creates a new ProblemBuilder for fluent problem construction.

```APIDOC
## static ProblemBuilder builder()

### Description
Creates a new ProblemBuilder for fluent problem construction. Allows flexible construction of problems with custom types, titles, and additional properties.

### Return Type
ProblemBuilder
```

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

### Implement Exceptional Interface

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Exceptional.md

Demonstrates how to implement the Exceptional interface in a custom exception class to maintain Problem semantics while extending another base class.

```java
// Option 1: Extend ThrowableProblem
public class OutOfStockProblem extends ThrowableProblem {
    // Cannot extend BusinessException
}

// Option 2: Extend custom exception + implement Exceptional
public class OutOfStockException extends BusinessException implements Exceptional {
    // Can extend BusinessException while implementing Problem
}
```

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

### Handle NullPointerException in Problem construction

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Demonstrates a scenario where a NullPointerException might occur if neither title nor detail is provided, and the recommended fix using builder methods.

```java
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.INTERNAL_SERVER_ERROR)
    // No title or detail
    .build();

String message = problem.getMessage();
// Returns empty string or null depending on stream filtering
```

```java
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.INTERNAL_SERVER_ERROR)
    .withTitle("Internal Server Error")
    .withDetail("An unexpected error occurred")
    .build();

String message = problem.getMessage();  // "Internal Server Error: An unexpected error occurred"
```

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

### Configure Java Module System

Source: https://github.com/zalando/problem/blob/main/README.md

Declare the required modules in your module-info.java file to ensure compatibility with JPMS.

```java
module org.example {
    requires org.zalando.problem;
    // pick needed dependencies
    requires org.zalando.problem.jackson;
    requires org.zalando.problem.gson;
}
```

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

### Implementing Exceptional and Configuring JsonMapper

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Demonstrates defining a custom exception implementing Exceptional and registering it with the ProblemModule in a JsonMapper.

```java
public class OutOfStockException extends BusinessException implements Exceptional {
    // implementation
}

JsonMapper mapper = JsonMapper.builder()
    .registerSubtypes(OutOfStockException.class)
    .addModule(new ProblemModule())
    .build();

String json = mapper.writeValueAsString(new OutOfStockException("B00027Y5QG"));
// Stack trace is handled appropriately based on module configuration
```

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

### Resolve ClassNotFoundException for ProblemModule

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Shows how to identify a missing module dependency and provides the necessary configuration for Maven and Gradle.

```java
// If problem-jackson3 not added to dependencies
JsonMapper mapper = JsonMapper.builder()
    .findAndAddModules()  // Does not find ProblemModule if not on classpath
    .build();
```

```xml
<!-- Maven -->
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-jackson3</artifactId>
    <version>${problem.version}</version>
</dependency>
```

```gradle
// Gradle
implementation 'org.zalando:problem-jackson3:${problemVersion}'
```

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

### Initialize AbstractThrowableProblem with all fields and cause

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance specifying all standard problem fields and an optional causal ThrowableProblem.

```java
protected AbstractThrowableProblem(@Nullable final URI type, 
                                  @Nullable final String title, 
                                  @Nullable final StatusType status, 
                                  @Nullable final String detail, 
                                  @Nullable final URI instance, 
                                  @Nullable final ThrowableProblem cause)
```

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

### Implement Custom Problem Classes

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Shows two approaches for implementing custom problem exceptions: extending ThrowableProblem or implementing the Exceptional interface.

```java
public class OutOfStockProblem extends ThrowableProblem {
    // Direct RuntimeException subclass
}
```

```java
public class OutOfStockException extends BusinessException implements Exceptional {
    // Can extend a custom exception base class
}
```

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

### Set Problem Detail

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Provide a context-specific explanation for the problem occurrence.

```java
public ProblemBuilder withDetail(@Nullable final String detail)
```

```java
ProblemBuilder builder = Problem.builder()
    .withDetail("Item B00027Y5QG is no longer available");
```

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

### ProblemModule Configuration Methods

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Method signatures for enabling or disabling stack trace serialization.

```java
public ProblemModule withStackTraces()
```

```java
public ProblemModule withStackTraces(final boolean stackTraces)
```

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

### Retrieve Problem Title

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Demonstrates retrieving the problem title using getTitle().

```java
public String getTitle()
```

```java
public class OutOfStockProblem extends AbstractThrowableProblem {
    public OutOfStockProblem(String product) {
        super(
            URI.create("https://example.org/out-of-stock"),
            "Out of Stock",
            Status.BAD_REQUEST
        );
    }
}

OutOfStockProblem problem = new OutOfStockProblem("B00027Y5QG");
assert problem.getTitle().equals("Out of Stock");
```

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

### Initialize AbstractThrowableProblem with type URI

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance specifying only the problem type URI.

```java
protected AbstractThrowableProblem(@Nullable final URI type)
```

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

### Problem.builder()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

The builder interface allows for the construction of ThrowableProblem instances with standard RFC 7807 fields and custom properties.

```APIDOC
## Problem.builder()

### Description
Constructs a new ThrowableProblem instance using a fluent builder pattern. This is the primary method for creating custom error responses.

### Methods
- **withType(URI type)**: Sets the problem type URI.
- **withTitle(String title)**: Sets the short, human-readable summary of the problem.
- **withStatus(Status status)**: Sets the HTTP status code.
- **withDetail(String detail)**: Sets a human-readable explanation specific to this occurrence.
- **withInstance(URI instance)**: Sets the URI reference that identifies the specific occurrence of the problem.
- **with(String key, Object value)**: Adds a custom property to the problem object.
- **build()**: Returns the constructed ThrowableProblem instance.

### Example
```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://api.example.org/problems/validation-error"))
    .withTitle("Validation Error")
    .withStatus(Status.UNPROCESSABLE_ENTITY)
    .withDetail("Email field contains invalid format")
    .with("field", "email")
    .build();
```
```

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

### withTitle(String)

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Sets the short, human-readable summary of the problem.

```APIDOC
## withTitle(String)

### Description
Sets the short, human-readable summary of the problem. The title should not change from occurrence to occurrence, except for localization purposes.

### Parameters
- **title** (String) - Optional - Short, human-readable summary

### Return Type
ProblemBuilder (for method chaining)
```

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

### Initialize AbstractThrowableProblem with default constructor

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance with all fields set to null and a default type of about:blank.

```java
protected AbstractThrowableProblem()
```

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

### Create Generic Problems

Source: https://github.com/zalando/problem/blob/main/README.md

Constructs a problem instance using only an HTTP status code or with an additional detail string.

```java
var problem = Problem.valueOf(Status.NOT_FOUND);
```

```java
var problem = Problem.valueOf(Status.SERVICE_UNAVAILABLE, "Database not reachable");
```

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

### Garbage Collection of DefaultProblem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

Demonstrates that DefaultProblem instances are eligible for garbage collection once unreferenced, requiring no manual cleanup.

```java
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.BAD_REQUEST)
    .build();

// No need to explicitly clean up; GC will collect when unused
problem = null;
```

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

### version()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Retrieves the version of the module.

```APIDOC
## public Version version()

### Description
Returns the module version, which is automatically determined from the Maven artifact version.

### Return Type
Version
```

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

### ProblemAdapterFactory()

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Initializes a new ProblemAdapterFactory instance for use with GsonBuilder.

```APIDOC
## ProblemAdapterFactory()

### Description
Initializes a new instance of the ProblemAdapterFactory to be registered with a GsonBuilder.

### Method
Constructor

### Parameters
- **statusTypes** (Class<? extends StatusType>...) - Optional - Custom HTTP status type enumerations.
```

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

### Use propagate Method

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Exceptional.md

Demonstrates using the propagate method to throw an Exceptional problem instance.

```java
public class OutOfStockException extends BusinessException implements Exceptional {
    @Override
    public URI getType() { return URI.create("https://example.org/out-of-stock"); }
    @Override
    public String getTitle() { return "Out of Stock"; }
    @Override
    public StatusType getStatus() { return Status.BAD_REQUEST; }
}

// Usage
try {
    readRemoteProblem();
} catch (Exception e) {
    throw ((Exceptional) e).propagate();
}
```

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

### Initialize AbstractThrowableProblem with type, title, and status

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Creates an instance specifying the problem type, title, and HTTP status code.

```java
protected AbstractThrowableProblem(@Nullable final URI type, 
                                  @Nullable final String title, 
                                  @Nullable final StatusType status)
```

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

### Constructing a Problem with ProblemBuilder

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Demonstrates building a ThrowableProblem with custom fields and standard RFC 7807 properties. Note that the builder is not thread-safe, but the resulting object is.

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(Status.BAD_REQUEST)
    .withDetail("Item B00027Y5QG is no longer available")
    .withInstance(URI.create("https://api.example.org/orders/123"))
    .with("product_id", "B00027Y5QG")
    .with("requested_quantity", 5)
    .build();

// Can be thrown as an exception
throw problem;

// Or serialized to JSON
String json = objectMapper.writeValueAsString(problem);
// Result:
// {
//   "type": "https://example.org/out-of-stock",
//   "title": "Out of Stock",
//   "status": 400,
//   "detail": "Item B00027Y5QG is no longer available",
//   "instance": "https://api.example.org/orders/123",
//   "product_id": "B00027Y5QG",
//   "requested_quantity": 5
// }
```

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

### Create Problem with Factory Methods

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/StatusType.md

Illustrates using Problem.valueOf to create instances with specific status types.

```java
// Standard status
ThrowableProblem problem1 = Problem.valueOf(Status.NOT_FOUND);

// Custom status
ThrowableProblem problem2 = Problem.valueOf(CustomStatus.CUSTOM_ERROR);
```

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

### Create Problem from Status Code

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Instantiate a ThrowableProblem using a predefined status code.

```java
ThrowableProblem problem = Problem.valueOf(Status.INTERNAL_SERVER_ERROR);
throw problem;
```

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

### Create Problem with Instance URI

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Creates a problem instance from a status code and an optional URI identifying the specific occurrence.

```java
static ThrowableProblem valueOf(final StatusType status, @Nullable final URI instance)
```

```java
URI instance = URI.create("https://example.org/problems/user/123");
ThrowableProblem problem = Problem.valueOf(Status.NOT_FOUND, instance);
```

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

### Throwing Problems as Exceptions

Source: https://github.com/zalando/problem/blob/main/README.md

Demonstrates how to inherit from AbstractThrowableProblem or implement the Exceptional interface to use problems as exceptions.

```java
public final class OutOfStockProblem extends AbstractThrowableProblem {
    // constructor
}
```

```java
public final class OutOfStockProblem extends BusinessException implements Exceptional
```

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

### Implement Immutable Problem Subclasses

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Demonstrates the difference between mutable and immutable Problem implementations to ensure consistent field values.

```java
// ✗ Bad - values change between calls
public class BadProblem extends AbstractThrowableProblem {
    @Override
    public String getTitle() {
        return new SimpleDateFormat().format(new Date());  // Changes every call
    }
}
```

```java
// ✓ Good - immutable
public class GoodProblem extends AbstractThrowableProblem {
    private final String title;
    
    public GoodProblem(String title) {
        super(null, title, null);
        this.title = title;
    }
}
```

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

### Add Custom Properties to Problem

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Use the with() method on the builder to include arbitrary key-value pairs in the problem output.

```java
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.BAD_REQUEST)
    .with("field", "email")
    .with("reason", "invalid_format")
    .with("value", "user@")
    .build();
```

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

### Catching ThrowableProblem exceptions

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Demonstrates catching a Problem instance thrown as a ThrowableProblem to inspect its properties.

```java
try {
    throw Problem.valueOf(Status.NOT_FOUND, "User 123 not found");
} catch (ThrowableProblem e) {
    log.warn("Resource not found: {}", e.getDetail());
}
```

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

### Retrieve Instance URI

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Method signature for retrieving the instance URI.

```java
public URI getInstance()
```

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

### Create Causal Chains with DefaultProblem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

Demonstrates nesting problems by attaching a cause to a ThrowableProblem using the builder pattern.

```java
ThrowableProblem databaseError = Problem.builder()
    .withType(URI.create("https://example.org/database-error"))
    .withStatus(Status.INTERNAL_SERVER_ERROR)
    .withTitle("Database Error")
    .build();

ThrowableProblem orderError = Problem.builder()
    .withType(URI.create("https://example.org/order-error"))
    .withStatus(Status.BAD_REQUEST)
    .withTitle("Order Processing Failed")
    .withCause(databaseError)
    .build();

ThrowableProblem cause = orderError.getCause();
assert cause.getTitle().equals("Database Error");
```

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

### Display File Organization Structure

Source: https://github.com/zalando/problem/blob/main/_autodocs/MANIFEST.md

Visual representation of the documentation directory structure.

```text
output/
├── README.md                              (Master index)
├── types.md                               (Type definitions)
├── configuration.md                       (Setup & options)
├── errors.md                              (Error reference)
└── api-reference/                         (Class/method docs)
    ├── Problem.md
    ├── ProblemBuilder.md
    ├── ThrowableProblem.md
    ├── AbstractThrowableProblem.md
    ├── DefaultProblem.md
    ├── Status.md
    ├── StatusType.md
    ├── Exceptional.md
    └── ProblemModule.md
```

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

### Configure ProblemModule with Jackson 2

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Basic initialization of the ProblemModule within a Jackson JsonMapper.

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule())
    .build();
```

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

### Handle Problem Exceptions

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Demonstrates catching specific and generic problem exceptions in a standard Java try-catch block.

```java
try {
    processOrder(order);
} catch (OutOfStockProblem e) {
    handleOutOfStock(e.getProduct());
} catch (ThrowableProblem e) {
    handleGenericProblem(e);
}
```

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

### Add Maven Dependencies

Source: https://github.com/zalando/problem/blob/main/README.md

Include these dependencies in your project's pom.xml to use the core library and optional Jackson or Gson support.

```xml
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem</artifactId>
    <version>${problem.version}</version>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-jackson3</artifactId>
    <version>${problem.version}</version>
</dependency>
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-gson</artifactId>
    <version>${problem.version}</version>
</dependency>
```

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

### Serialize Basic Problem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Serializes a standard Problem instance to JSON.

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule())
    .build();

ThrowableProblem problem = Problem.valueOf(Status.NOT_FOUND);
String json = mapper.writeValueAsString(problem);
// Result:
// {"title":"Not Found","status":404}
```

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

### Constructing Problems with the Builder Pattern

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Use the fluent API to construct Problem instances with specific fields like type, title, status, and detail.

```java
// Fluent API for constructing problems
Problem problem = Problem.builder()
    .withType(...)
    .withTitle(...)
    .withStatus(...)
    .withDetail(...)
    .with(...)
    .build();
```

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

### Enable Stack Trace Serialization

Source: https://github.com/zalando/problem/blob/main/README.md

Configure the ProblemModule to include stack traces in serialized output.

```java
JsonMapper mapper = JsonMapper.builder()
        .addModule(new ProblemModule().withStackTraces())
        .build();
```

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

### Retrieve HTTP Status Code

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Demonstrates retrieving the HTTP status code using getStatus().

```java
public StatusType getStatus()
```

```java
AbstractThrowableProblem problem = new OutOfStockProblem("B00027Y5QG");
StatusType status = problem.getStatus();
assert status.equals(Status.BAD_REQUEST);
```

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

### with(String, Object)

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Adds a custom property to the problem instance. Throws an IllegalArgumentException if the key is a reserved property name.

```APIDOC
## with(String, Object)

### Description
Adds a custom property to the problem. Custom properties extend the problem beyond standard RFC 7807 fields.

### Signature
`public ProblemBuilder with(final String key, @Nullable final Object value)`

### Parameters
- **key** (String) - Required - Property name
- **value** (Object) - Optional - Property value

### Returns
- **ProblemBuilder** - The builder instance for method chaining.

### Throws
- **IllegalArgumentException** - If key is a reserved property (type, title, status, detail, instance, cause).
```

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

### Add Custom Properties

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

Include additional metadata like trace IDs or timestamps to aid in troubleshooting.

```java
// ✓ Good
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.INTERNAL_SERVER_ERROR)
    .with("trace_id", UUID.randomUUID().toString())
    .with("request_id", requestId)
    .with("timestamp", Instant.now())
    .build();
```

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

### Retrieve Problem Detail

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Access the specific human-readable explanation for the problem occurrence.

```java
Problem problem = Problem.valueOf(Status.NOT_FOUND, "User ID 12345 not found");
String detail = problem.getDetail(); // Returns "User ID 12345 not found"
```

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

### Retrieve Custom Parameters

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/AbstractThrowableProblem.md

Demonstrates retrieving custom properties as an immutable map using getParameters().

```java
public Map<String, Object> getParameters()
```

```java
Map<String, Object> params = problem.getParameters();
// Returns immutable map of custom properties
```

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

### Serialize Problem with Details

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Serializes a Problem instance containing custom fields and detailed information.

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(Status.BAD_REQUEST)
    .withDetail("Item B00027Y5QG is no longer available")
    .with("product_id", "B00027Y5QG")
    .build();

String json = mapper.writeValueAsString(problem);
// Result:
// {
//   "type":"https://example.org/out-of-stock",
//   "title":"Out of Stock",
//   "status":400,
//   "detail":"Item B00027Y5QG is no longer available",
//   "product_id":"B00027Y5QG"
// }
```

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

### Add Jackson 2 Module Dependency

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Include the Jackson 2.x serialization support module.

```xml
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-jackson2</artifactId>
    <version>${problem.version}</version>
</dependency>
```

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

### Retrieve HTTP reason phrase

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Status.md

Returns the standard reason phrase for the status code.

```java
public String getReasonPhrase()
```

```java
String phrase = Status.NOT_FOUND.getReasonPhrase();
// Returns: "Not Found"
```

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

### ProblemModule(StatusType... statusTypes)

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Constructor for initializing the ProblemModule with optional custom status type enumerations.

```APIDOC
## ProblemModule(StatusType... statusTypes)

### Description
Initializes the ProblemModule. You can pass one or more classes implementing StatusType to support custom HTTP status codes.

### Parameters
- **statusTypes** (Class<? extends StatusType>...) - Optional - Custom HTTP status type enumerations.

### Example
```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule(CustomStatus.class))
    .build();
```
```

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

### Implementing Exceptional with a custom base class

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Exceptional.md

Create a custom exception hierarchy by implementing the Exceptional interface and wrapping a Problem instance.

```java
public abstract class ApiException extends RuntimeException implements Exceptional {
    
    private final Problem problem;

    public ApiException(Problem problem) {
        super(problem.getTitle());
        this.problem = problem;
    }

    @Override
    public URI getType() { return problem.getType(); }

    @Override
    public String getTitle() { return problem.getTitle(); }

    @Override
    public StatusType getStatus() { return problem.getStatus(); }

    @Override
    public String getDetail() { return problem.getDetail(); }

    @Override
    public URI getInstance() { return problem.getInstance(); }

    @Override
    public Exceptional getCause() { return null; }

    @Override
    public Map<String, Object> getParameters() {
        return problem.getParameters();
    }
}

// Specific exceptions
public class OutOfStockException extends ApiException {
    private final String product;

    public OutOfStockException(String product) {
        super(Problem.builder()
            .withType(URI.create("https://example.org/out-of-stock"))
            .withTitle("Out of Stock")
            .withStatus(Status.BAD_REQUEST)
            .withDetail("Item " + product + " is no longer available")
            .build());
        this.product = product;
    }

    public String getProduct() { return product; }
}
```

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

### Set Instance URI

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Define an absolute URI to distinguish specific occurrences of a problem.

```java
public ProblemBuilder withInstance(@Nullable final URI instance)
```

```java
URI instance = URI.create("https://example.org/problems/order/12345");
ProblemBuilder builder = Problem.builder()
    .withInstance(instance);
```

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

### Add Jackson 3 Module Dependency

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Include the Jackson 3.x serialization support module.

```xml
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-jackson3</artifactId>
    <version>${problem.version}</version>
</dependency>
```

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

### withDetail(String)

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Sets the human-readable explanation specific to this occurrence.

```APIDOC
## withDetail(String)

### Description
Sets the human-readable explanation specific to this occurrence, providing context about why the problem occurred.

### Parameters
- **detail** (String) - Optional - Human-readable explanation

### Return Type
ProblemBuilder (for method chaining)
```

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

### Add Gson Module Dependency

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Include the Google Gson serialization support module.

```xml
<dependency>
    <groupId>org.zalando</groupId>
    <artifactId>problem-gson</artifactId>
    <version>${problem.version}</version>
</dependency>
```

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

### Set Problem Title

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Define a short, human-readable summary for the problem.

```java
public ProblemBuilder withTitle(@Nullable final String title)
```

```java
ProblemBuilder builder = Problem.builder()
    .withTitle("Out of Stock");
```

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

### Construct Problems with Builder

Source: https://github.com/zalando/problem/blob/main/README.md

Uses a fluent API to define specific problem types and custom properties without creating custom classes.

```java
var problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(BAD_REQUEST)
    .withDetail("Item B00027Y5QG is no longer available")
    .build();
```

```java
var problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(BAD_REQUEST)
    .withDetail("Item B00027Y5QG is no longer available")
    .with("product", "B00027Y5QG")
    .build();
```

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

### ProblemModule(Class<? extends E>...)

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Initializes the ProblemModule with custom status type enumerations.

```APIDOC
## ProblemModule(Class<? extends E>...)

### Description
Constructor that allows registering custom StatusType enum implementations alongside or instead of the standard Status enum.

### Signature
`public <E extends Enum<?> & StatusType> ProblemModule(final Class<? extends E>... types)`

### Parameters
- **types** (Class<? extends E>[]) - Required - Status type enums to register.

### Throws
- **IllegalArgumentException** - Thrown if status codes are duplicated across the provided enums.

### Example
```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule(CustomStatus.class))
    .build();
```
```

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

### withStackTraces()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Enables serialization of stack traces for Problem objects. Returns a new immutable instance of the module.

```APIDOC
## public ProblemModule withStackTraces()

### Description
Enables serialization of stack traces (default: disabled). Returns a new module instance with stack trace serialization enabled.

### Return Type
ProblemModule (new instance)

### Example
```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule().withStackTraces())
    .build();
```
```

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

### Register Unique Problem Subtypes

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Shows the correct approach to registering problem subtypes using unique URIs.

```java
new ProblemAdapterFactory()
    .registerSubtype(
        URI.create("https://example.org/out-of-stock"),
        OutOfStockProblem.class
    )
    .registerSubtype(
        URI.create("https://example.org/insufficient-funds"),  // ✓ Different URI
        InsufficientFundsProblem.class
    )
```

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

### Configure JsonMapper for environments

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Configure the ProblemModule within a JsonMapper, adjusting stack trace visibility based on the environment.

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(
        new ProblemModule()
            .withStackTraces()  // Enable for debugging
    )
    .build();
```

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(
        new ProblemModule()
            // Stack traces disabled by default
    )
    .build();
```

```java
boolean isDebug = environment.getProperty("app.debug", false);

JsonMapper mapper = JsonMapper.builder()
    .addModule(
        new ProblemModule()
            .withStackTraces(isDebug)
    )
    .build();
```

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

### Handle JsonMappingException and Register Subtypes

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Shows how to handle mapping errors when types are missing and how to register custom subtypes for correct deserialization.

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule())
    .registerSubtypes(OutOfStockProblem.class)
    .build();

try {
    String json = "{\"type\": \"https://example.org/unknown-type\", \"status\": 400}";
    Problem problem = mapper.readValue(json, Problem.class);
    // Falls back to DefaultProblem since type is not registered
} catch (JsonMappingException e) {
    log.error("Cannot map JSON to problem type: {}", e.getMessage());
}
```

```java
mapper.builder()
    .registerSubtypes(
        OutOfStockProblem.class,
        InvalidCouponProblem.class
    )
    .addModule(new ProblemModule())
    .build();
```

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

### ProblemBuilder.build()

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemBuilder.md

Constructs a ThrowableProblem instance using the configured properties. The builder is not thread-safe, but the resulting object is immutable.

```APIDOC
## ProblemBuilder.build()

### Description
Constructs a `ThrowableProblem` instance based on the properties configured via the builder methods. The resulting object is immutable and thread-safe.

### Methods
- `withType(URI type)`: Sets the problem type URI.
- `withTitle(String title)`: Sets the short summary of the problem.
- `withStatus(Status status)`: Sets the HTTP status code.
- `withDetail(String detail)`: Sets the occurrence-specific explanation.
- `withInstance(URI instance)`: Sets the instance URI.
- `with(String key, Object value)`: Adds custom properties to the problem object. Note: Reserved properties (type, title, status, detail, instance, cause) cannot be set via this method.

### Usage Example
```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/out-of-stock"))
    .withTitle("Out of Stock")
    .withStatus(Status.BAD_REQUEST)
    .withDetail("Item B00027Y5QG is no longer available")
    .with("product_id", "B00027Y5QG")
    .build();
```
```

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

### Create Problem with Detail Message

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Creates a problem instance from a status code and an optional human-readable detail message.

```java
static ThrowableProblem valueOf(final StatusType status, @Nullable final String detail)
```

```java
ThrowableProblem problem = Problem.valueOf(Status.SERVICE_UNAVAILABLE, "Database not reachable");
// Produces: {"title": "Service Unavailable", "status": 503, "detail": "Database not reachable"}
```

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

### Integrate with Jackson

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Configures a JsonMapper with the ProblemModule to enable serialization and deserialization of Problem objects.

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(new ProblemModule())
    .build();

// Serialize
String json = mapper.writeValueAsString(problem);

// Deserialize
Problem problem = mapper.readValue(json, Problem.class);
```

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

### Create Problem with Details

Source: https://github.com/zalando/problem/blob/main/_autodocs/README.md

Use the fluent builder to construct a problem with custom title and detail fields.

```java
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.NOT_FOUND)
    .withTitle("Not Found")
    .withDetail("User 123 not found")
    .build();
throw problem;
```

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

### ProblemAdapterFactory Method Signatures

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Method signatures for configuring stack traces and registering subtypes.

```java
public ProblemAdapterFactory withStackTraces()
```

```java
public ProblemAdapterFactory withStackTraces(final boolean stackTraces)
```

```java
public ProblemAdapterFactory registerSubtype(
    final URI uri, 
    final Class<? extends Problem> type)
```

```java
public ProblemAdapterFactory registerSubType(
    final URI uri, 
    final TypeToken<? extends Problem> type)
```

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

### Capture Stack Traces in DefaultProblem

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/DefaultProblem.md

DefaultProblem captures the stack trace at the point of instantiation.

```java
ThrowableProblem problem = Problem.builder()
    .withStatus(Status.INTERNAL_SERVER_ERROR)
    .build();

StackTraceElement[] stackTrace = problem.getStackTrace();
// Stack trace captured at Problem.builder().build() call site
```

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

### Implementing StackTraceProcessor SPI

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ProblemModule.md

Shows how to implement the StackTraceProcessor interface to filter or modify stack trace elements during serialization.

```java
public class MyStackTraceProcessor implements StackTraceProcessor {
    @Override
    public Collection<StackTraceElement> process(Collection<StackTraceElement> elements) {
        // Filter or modify stack trace elements
        return elements.stream()
            .filter(e -> e.getClassName().startsWith("com.example"))
            .collect(Collectors.toList());
    }
}
```

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

### Handle Duplicate Problem Type Registration

Source: https://github.com/zalando/problem/blob/main/_autodocs/errors.md

Demonstrates catching an IllegalArgumentException when attempting to register the same URI for multiple problem types.

```java
try {
    new ProblemAdapterFactory()
        .registerSubtype(
            URI.create("https://example.org/out-of-stock"),
            OutOfStockProblem.class
        )
        .registerSubtype(
            URI.create("https://example.org/out-of-stock"),  // ✗ Duplicate
            AnotherOutOfStockProblem.class
        );
} catch (IllegalArgumentException e) {
    log.error("Duplicate problem type registration: {}", e.getMessage());
    // Message: "class & type must be unique"
}
```

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

### Use propagateAs Method

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Exceptional.md

Demonstrates using the propagateAs method to cast and throw an Exceptional problem as a specific exception type.

```java
public class OutOfStockException extends BusinessException implements Exceptional {
    // implements Exceptional interface
}

// Usage
try {
    readRemoteProblem();
} catch (Exception e) {
    throw ((Exceptional) e).propagateAs(OutOfStockException.class);
}
```

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

### ThrowableProblem String Representation

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/ThrowableProblem.md

Generates a formatted string representation of the problem instance.

```java
public String toString()
```

```java
ThrowableProblem problem = Problem.builder()
    .withType(URI.create("https://example.org/problem"))
    .withTitle("Oh, oh!")
    .withStatus(Status.UNPROCESSABLE_ENTITY)
    .withDetail("Crap.")
    .withInstance(URI.create("https://example.org/problem/123"))
    .build();

String str = problem.toString();
// Returns: "https://example.org/problem{422, Oh, oh!, Crap., instance=https://example.org/problem/123}"
```

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

### Retrieve Problem Title

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Access the human-readable summary of the problem type.

```java
Problem problem = Problem.valueOf(Status.NOT_FOUND);
String title = problem.getTitle(); // Returns "Not Found"
```

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

### Configure Jackson for Problem

Source: https://github.com/zalando/problem/blob/main/_autodocs/configuration.md

Configures a JsonMapper with ProblemModule and registers specific problem subtypes for serialization and deserialization.

```java
JsonMapper mapper = JsonMapper.builder()
    .addModule(
        new ProblemModule(CustomStatus.class)
            .withStackTraces()
    )
    .registerSubtypes(
        OutOfStockProblem.class,
        InsufficientFundsProblem.class,
        InvalidCouponProblem.class
    )
    .build();

// Serialize
ThrowableProblem problem = new OutOfStockProblem("B00027Y5QG");
String json = mapper.writeValueAsString(problem);

// Deserialize
String responseJson = httpClient.get("/orders/123");
ThrowableProblem response = mapper.readValue(responseJson, ThrowableProblem.class);
```

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

### Create Problem from Status Code

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Problem.md

Creates a generic problem instance using only an HTTP status code.

```java
static ThrowableProblem valueOf(final StatusType status)
```

```java
ThrowableProblem problem = Problem.valueOf(Status.NOT_FOUND);
// Produces: {"title": "Not Found", "status": 404}
```

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

### Exceptional.propagateAs(Class<X>)

Source: https://github.com/zalando/problem/blob/main/_autodocs/api-reference/Exceptional.md

Throws the problem as a specific exception type.

```APIDOC
## Exceptional.propagateAs(Class<X>)

### Description
Throws this problem as a specific exception type.

### Signature
`default <X extends Throwable> X propagateAs(final Class<X> type) throws X`

### Parameters
- **type** (Class<X>) - Required - Exception type to throw as

### Throws
`X` - Always throws this problem instance cast to the specified type
```
Tokens:
Raw