Error Handling — Aquilia Documentation
Comprehensive guide and documentation for Error Handling in the Aquilia framework. View API reference, examples, and implementation patterns.
HTTP Client / Error Handling Fault System Structured error handling with typed faults, metadata, and domain-specific error codes. Why Faults? Aquilia uses structured faults instead of raw exceptions for better error handling: ))} Fault Hierarchy Fault (base class for all Aquilia errors) └─ HTTPClientFault (domain: HTTP_CLIENT) ├─ ConnectionFault (CONNECTION_FAILED) ├─ TimeoutFault (TIMEOUT) │ ├─ ConnectTimeoutFault (CONNECT_TIMEOUT) │ ├─ ReadTimeoutFault (READ_TIMEOUT) │ └─ WriteTimeoutFault (WRITE_TIMEOUT) ├─ TLSFault (TLS_ERROR) │ └─ CertificateVerifyFault (CERT_VERIFY_FAILED) ├─ HTTPStatusFault (HTTP_STATUS_ERROR) │ ├─ ClientErrorFault (4xx) │ └─ ServerErrorFault (5xx) ├─ RetryExhaustedFault (RETRY_EXHAUSTED) ├─ RedirectFault (TOO_MANY_REDIRECTS) └─ TransportFault (TRANSPORT_ERROR) ConnectionFault Raised when a TCP socket connection fails: from aquilia.http.faults import ConnectionFault try: response = await client.get("https://nonexistent-host.invalid") except ConnectionFault as e: print(f"Code: ") # CONNECTION_FAILED print(f"Message: ") # "Connection failed: ..." print(f"Domain: ") # HTTP_CLIENT # Metadata print(f"Host: ") print(f"Port: ") TimeoutFault Raised when a network operation exceeds a defined timeout limit: from aquilia.http.faults import ( TimeoutFault, ConnectTimeoutFault, ReadTimeoutFault, ) try: response = await client.get("https://slow-api.com") except TimeoutFault as e: print(f"Timeout: s") print(f"Phase: ") # connect/read/write try: response = await client.get("https://slow-connect.com") except ConnectTimeoutFault: print("Connection timed out") TLSFault Raised for SSL/TLS handshaking or validation errors: from aquilia.http.faults import TLSFault, CertificateVerifyFault try: response = await client.get("https://expired-cert.badssl.com") except TLSFault as e: print(f"TLS error: ") try: response = await client.get("https://self-signed.badssl.com") except CertificateVerifyFault as e: print("Certificate verification failed") HTTPStatusFault Raised for non-2xx status codes when using raise_for_status(): from aquilia.http.faults import HTTPStatusFault, ClientErrorFault, ServerErrorFault response = await client.get("/api/users/9999") try: response.raise_for_status() except HTTPStatusFault as e: print(f"Status: ") # 404 print(f"Message: ") # "HTTP 404: Not Found" try: response = await client.get("/api/protected") response.raise_for_status() except ClientErrorFault as e: if e.status_code == 401: print("Unauthorized") Advanced Usage DI Integration )
Go to Homepage