Principle:Eventual Inc Daft Error Hierarchy
| Knowledge Sources | |
|---|---|
| Domains | Error_Handling, FFI |
| Last Updated | 2026-02-08 14:00 GMT |
Overview
Design pattern that defines a structured exception class hierarchy enabling callers to catch errors at the appropriate granularity, from broad base classes to specific transient network errors.
Description
A structured error hierarchy organizes exceptions into a tree where each level represents a category of failure. The base exception provides a catch-all for any framework error, while specialized subclasses allow targeted error handling. For Rust-Python hybrid systems, this hierarchy is shared across the language boundary: the Rust engine maps its error types to specific Python exception classes via PyO3, ensuring that Python callers see semantically meaningful exceptions rather than generic `RuntimeError`.
The transient error branch is particularly important for distributed systems where network failures (timeouts, throttling, socket errors) should be retried, while type errors and other permanent failures should not.
Usage
Apply this principle when building a library with a Rust backend that raises errors into Python, or any system where callers need to distinguish between retryable and permanent failures. Users catch specific subclasses for retry logic and the base class for general error handling.
Theoretical Basis
Exception hierarchies follow the Liskov Substitution Principle: catching a base class should handle all its subclasses. The hierarchy partitions the error space:
- Permanent errors (type mismatches, schema violations) should fail fast.
- Transient errors (timeouts, throttling, socket errors) should trigger retry logic.
This partition enables callers to write correct retry logic without enumerating individual error types.