Exceptions

Honey Badgeria provides a complete exception hierarchy. Every exception raised by the framework is a subclass of HoneyBadgeriaError, making it easy to catch all HBIA-related errors.

Exception Tree

HoneyBadgeriaError                    # Universal catch-all
├── GraphError                        # Graph structure issues
│   ├── VertexAlreadyExistsError     # Duplicate vertex name
│   ├── VertexNotFoundError          # Reference to non-existent vertex
│   ├── EdgeInvalidError             # Invalid edge (missing endpoint)
│   └── GraphCycleError              # Cycle detected in DAG
├── GraphValidationError              # Graph validation failed (.errors: list[str])
├── DSLValidationError                # YAML DSL validation failed (.errors: list[str])
├── HandlerNotFoundError              # No handler for vertex name
├── HandlerResolutionError            # Handler import failed or blocked
├── FlowNotFoundError                 # Named flow doesn't exist
├── DataResolutionError               # Data binding cannot be resolved
├── ContractError                     # Input/output contract violation
│   ├── ContractInputError           # Input doesn't match contract
│   └── ContractOutputError          # Output doesn't match contract
├── CacheError                        # Cache operation failed
├── ExecutionError                    # Runtime execution failure
│   ├── VertexExecutionError         # Single vertex failed (.vertex_name, .original)
│   └── StageExecutionError          # Execution stage failed
├── AtomicError                       # Atomicity failure
│   ├── AtomicRollbackError          # Rollback operation failed
│   ├── AtomicSnapshotError          # Snapshot capture failed
│   └── AtomicBoundaryError          # Atomic group boundary violation
├── SagaError                         # SAGA pattern failure
│   ├── SagaCompensationError        # Compensation(s) failed (.failures: list)
│   └── SagaStepError               # SAGA step failed (.step_name, .original)
└── ConfigurationError                # Invalid configuration

Usage Patterns

Catch All HBIA Errors

from honey_badgeria.core.exceptions import HoneyBadgeriaError

try:
    result = run_flow(graph, handlers={...})
except HoneyBadgeriaError as e:
    # Guaranteed to come from HBIA, not from user code
    log.error(f"HBIA error: {e}")

Catch Specific Error Categories

from honey_badgeria.core.exceptions import (
    GraphError,
    ExecutionError,
    ContractError,
    AtomicError,
    SagaError,
)

try:
    result = run_flow(graph, handlers={...})
except GraphError as e:
    # Graph structure issue (cycles, missing vertices)
    log.error(f"Graph error: {e}")
except ContractError as e:
    # Input/output type mismatch
    log.error(f"Contract violation: {e}")
except AtomicError as e:
    # Atomicity failure (rollback, snapshot)
    log.error(f"Atomic error: {e}")
except SagaError as e:
    # SAGA failure (compensation)
    log.error(f"SAGA error: {e}")
except ExecutionError as e:
    # Runtime execution failure
    log.error(f"Execution error: {e}")

Handling Vertex Errors

VertexExecutionError includes the vertex name and original exception:

from honey_badgeria.core.exceptions import VertexExecutionError

try:
    result = run_flow(graph, handlers={...})
except VertexExecutionError as e:
    print(f"Vertex '{e.vertex_name}' failed: {e.original}")

Handling Validation Errors

DSLValidationError and GraphValidationError include a list of error messages:

from honey_badgeria.core.exceptions import DSLValidationError, GraphValidationError

try:
    errors = validate_dsl(yaml_dict)
    if errors:
        raise DSLValidationError(errors)
except DSLValidationError as e:
    for error in e.errors:
        print(f"  - {error}")

Handling SAGA Errors

SagaCompensationError includes the list of compensation failures:

from honey_badgeria.core.exceptions import SagaCompensationError, SagaStepError

try:
    results = saga.execute(step_executor)
except SagaStepError as e:
    print(f"Step '{e.step_name}' failed: {e.original}")
except SagaCompensationError as e:
    print(f"Compensations failed: {e.failures}")

Import

All exceptions are available from:

from honey_badgeria.core.exceptions import (
    HoneyBadgeriaError,
    GraphError,
    VertexAlreadyExistsError,
    VertexNotFoundError,
    EdgeInvalidError,
    GraphCycleError,
    GraphValidationError,
    DSLValidationError,
    HandlerNotFoundError,
    HandlerResolutionError,
    FlowNotFoundError,
    DataResolutionError,
    ContractError,
    ContractInputError,
    ContractOutputError,
    CacheError,
    ExecutionError,
    VertexExecutionError,
    StageExecutionError,
    AtomicError,
    AtomicRollbackError,
    AtomicSnapshotError,
    AtomicBoundaryError,
    SagaError,
    SagaCompensationError,
    SagaStepError,
    ConfigurationError,
)