Errors
All public exceptions inherit from a base class for their domain. Catching the base class handles all errors within that domain.
Core Wallet
| Exception | Raised When |
|---|
WalletError | Base class for wallet operations |
WalletSyncError | wallet.sync() cannot reach the network backend |
InsufficientConfirmedFundsError | Confirmed UTXOs cannot cover amount + fees during approval |
ProposalNotFoundError | approve_proposal or reject_proposal called with invalid ID |
Transactions
| Exception | Raised When |
|---|
TransactionError | Base class for transaction construction/broadcast |
PSBTError | PSBT data is malformed or does not conform to BIP-174 |
BroadcastError | Transaction broadcast fails (network error) |
BroadcastRejectedError | Backend explicitly rejects the transaction (invalid, double-spend) |
UTXO Selection
| Exception | Raised When |
|---|
UTXOError | Base class for coin selection errors |
InsufficientFundsError | Available UTXOs cannot cover the requested amount + fees |
Policy
| Exception | Raised When |
|---|
PolicyError | Policy engine configuration error |
Fees / Watcher
| Exception | Raised When |
|---|
WatcherError | Watcher cannot complete a mempool query |
Note: FeeEstimator raises httpx.HTTPStatusError or httpx.TimeoutException directly (from the httpx library).
Lightning
| Exception | Raised When |
|---|
LightningError | Base class for all Lightning errors |
LightningConfigError | Invalid LND/CLN configuration (bad paths, missing files) |
LightningAuthError | Authentication or connectivity failure at init |
L402
| Exception | Raised When |
|---|
L402Error | Base class for L402 client errors |
L402ProtocolError | HTTP 402 response missing a valid challenge header/body |
L402PaymentError | Invoice payment or preimage extraction failed |
Audit
| Exception | Raised When |
|---|
| (none) | AuditLedger methods do not raise custom exceptions; I/O errors propagate as OSError |