Fault System — Aquilia Documentation
Comprehensive guide and documentation for Fault System in the Aquilia framework. View API reference, examples, and implementation patterns.
ADVANCED / FAULTS SYSTEM Structured Faults In Aquilia, errors are first-class structured values called Faults. Inheriting from Python's base Exception class, every Fault carries stable identifiers, classification domains, severity ratings, and recovery strategies. Why Structured Faults? Raw Python exceptions lack consistent structures, making it difficult for downstream HTTP middlewares or background workers to parse error details safely. A Fault encapsulates these properties: 1. ORIGIN Exception/Fault raised 2. ANNOTATION FaultContext wrapped 3. EMISSION Logs & listener dispatch 4. PROPAGATION Scope handler routing 5. RESOLUTION Resolved/Transformed result 6. RESPONSE Safe HTTP serialization Classification Domains Organizes errors by subsystem (e.g. CONFIG, DI, MODEL, CACHE), defining default severity and retry rules automatically. Public Exposure Controls The public boolean flag controls whether error messages can be returned directly to JSON clients or must be masked as 500 errors. Creating Faults from aquilia.faults import Fault, FaultDomain, Severity, RecoveryStrategy # Instantiating a structured fault raise Fault( code="USER_NOT_FOUND", message="Requested user ID does not exist", domain=FaultDomain.MODEL, severity=Severity.ERROR, public=True, retryable=False, user_id=123 # Arbitrary metadata fields are merged automatically ) Preserving Causality: Transform Chain Faults support the right shift operator >>. This allows handlers to catch lower-level errors (like database exceptions) and transform them into higher-level API faults while preserving causality: try: await db.execute("INSERT ...") except DatabaseError as err: # Transform lower-level database error to public API fault # Preserves the cause and updates the '_transform_chain' key in metadata raise DatabaseFault(code="DB_FAIL", message=str(err)) >> ApiFault("USER_CREATE_FAILED") Fault Taxonomy )
Go to Homepage