Skip to content

Exception Handling

The core modules use different exception hierarchies, for expressing errors at runtime.

Client Exceptions

The esdb-client module exposes the following exception hierarchy, when using EsdbClient operations:

classDiagram
    class ClientException
    class HttpException {
        +int statusCode
    }
    class HttpClientException
    class HttpServerException
    class InterruptedException
    class TransportException
    class InvalidUsageException
    class MarshallingException

    ClientException <|-- HttpException
    HttpException <|-- HttpClientException
    HttpException <|-- HttpServerException
    ClientException <|-- InterruptedException
    ClientException <|-- TransportException
    ClientException <|-- InvalidUsageException
    ClientException <|-- MarshallingException

The following table describes, which error cases are represented by each of these exceptions:

Exception Class Cause/Description
ClientException base class for all client-related exceptions, extending java.lang.RuntimeException
HttpException base class for HTTP status codes representing errors
HttpClientException represents HTTP 4xx client errors
HttpServerException represents HTTP 5xx server errors
InterruptedException represents thread interruption
TransportException represents network and connection errors
InvalidUsageException represents invalid Client API usage, e.g. conflicting preconditions or options
MarshallingException represents serialization/deserialization errors to/from JSON

Framework Exceptions

The framework module exposes the following exception hierarchy, when using any of its core components:

classDiagram
    class CqrsFrameworkException

    class TransientException
    class ClientInterruptedException
    class CommandSubjectDoesNotExistException
    class ConcurrencyException

    class NonTransientException
    class CommandSubjectAlreadyExistsException
    class EventTypeResolutionException 

    CqrsFrameworkException <|-- TransientException
    TransientException <|-- ClientInterruptedException
    TransientException <|-- CommandSubjectDoesNotExistException
    TransientException <|-- ConcurrencyException

    CqrsFrameworkException <|-- NonTransientException
    NonTransientException <|-- CommandSubjectAlreadyExistsException
    NonTransientException <|-- EventTypeResolutionException

Wrapped ClientException

As the module depends on the esdb-client, occurrences of ClientException and its subclasses are wrapped into framework-specific exception classes, so code using only framework components can rely on this exception hierarchy.

The following table describes, which error cases are represented by each of these exceptions:

Exception Class Cause/Description
CqrsFrameworkException base class for all framework related exceptions
TransientException represents potentially recoverable errors, worth retrying
ClientInterruptedException represents client thread interruption
CommandSubjectDoesNotExistException represents a missing or not yet existing target subject for a command execution
ConcurrencyException represents a concurrency error while publishing events from a command execution, typically due to violated preconditions
NonTransientException represents non-recoverable errors
CommandSubjectAlreadyExistsException represents a conflict, because a target subject for a command execution already exists
EventTypeResolutionException represents unresolvable event type errors

Additionally, the following occurrences of ClientException are wrapped into TransientException:

The following occurrences of ClientException are wrapped into NonTransientException: