APiGen Exceptions

RFC 7807 Problem Details for HTTP APIs - Standardized error handling for APiGen applications.

Overview

The Problem: Inconsistent Error Handling

Before APiGen Exceptions:

// ❌ Inconsistent error responses across services
// Service A returns:
{ "error": "Invalid email", "code": 400 }

// Service B returns:
{ "message": "Email validation failed", "status": "error" }

// Service C returns:
{ "errors": [{"field": "email", "msg": "Invalid"}] }

After APiGen Exceptions:

// ✅ Standardized RFC 7807 responses everywhere
{
  "type": "urn:apigen:problem:validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Email format is invalid",
  "instance": "/api/users",
  "timestamp": "2026-02-04T00:15:00Z",
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "extensions": {
    "field": "email",
    "pattern": "^[A-Za-z0-9+_.-]+@(.+)$"
  }
}

Features

• RFC 7807 Compliance - Standard application/problem+json responses
• Domain Exceptions - Typed exceptions for common business scenarios
• Request Tracking - Automatic requestId from MDC for distributed tracing
• Extensible - Custom fields via extensions map
• HTTP Status Mapping - Automatic @ResponseStatus annotations

Usage

Gradle:

dependencies {
    implementation 'com.jnzader:apigen-exceptions:1.0.0-SNAPSHOT'
}

Maven:

<dependency>
    <groupId>com.jnzader</groupId>
    <artifactId>apigen-exceptions</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Error Type URNs

APiGen uses URN namespace for error types:

URN	HTTP Status	Use Case
urn:apigen:problem:validation-error	400	Business validation failures
urn:apigen:problem:bad-request	400	Malformed requests
urn:apigen:problem:forbidden	403	Authorization failures
urn:apigen:problem:not-found	404	Resource not found
urn:apigen:problem:conflict	409	Resource conflicts
urn:apigen:problem:precondition-failed	412	Precondition not met
urn:apigen:problem:internal-error	500	Internal server errors
urn:apigen:problem:external-service-error	502	External service failures

Domain Exceptions

ValidationException (HTTP 400)

For business validation failures:

if (product.getPrice().compareTo(BigDecimal.ZERO) <= 0) {
    throw new ValidationException("Price must be positive");
}

OperationFailedException (HTTP 500)

For internal operation failures:

try {
    performCriticalOperation();
} catch (Exception e) {
    throw new OperationFailedException("Failed to process order", e);
}

ExternalServiceException (HTTP 502)

For external service integration failures:

try {
    paymentGateway.charge(order);
} catch (ApiException e) {
    throw new ExternalServiceException(
        "Stripe", 
        "Payment processing failed", 
        e.getMessage()
    );
}