Error Handling Reference
API Errors
DefiLlama API Unavailable
Error: Connection refused / timeout
Cause: DefiLlama bridges API is down or rate limited. Solution:
- Wait and retry with exponential backoff
- Use cached data if available
- Check DefiLlama status page
Bridge API Unavailable
Error: Protocol API not responding
Cause: Specific bridge API (Wormhole, LayerZero, etc.) is down. Solution:
- Try alternative tracking method (on-chain verification)
- Wait and retry
- Check bridge status page
Rate Limited
Error: 429 Too Many Requests
Cause: Exceeded API rate limits. Solution:
- Reduce request frequency
- Use caching more aggressively
- Spread requests over time
Transaction Tracking Errors
Transaction Not Found
Transaction not found in any bridge
Cause: TX hash doesn't match any known bridge. Solution:
- Verify the transaction hash is correct
- Specify the bridge with
--bridge - Specify source chain with
--chain - Transaction may be too old
Wrong Bridge Specified
Bridge not found: xyz
Cause: Bridge name not recognized. Solution:
- Use
python bridge_monitor.py protocolsto see supported bridges - Check spelling (case-insensitive)
- Use bridge ID instead of name
Pending Too Long
Transaction still pending after 60 minutes
Cause: Bridge congestion, low gas, or failure. Solution:
- Check source chain for confirmation
- Verify transaction wasn't reverted
- Contact bridge support if stuck
Chain Errors
Unsupported Chain
Error: No RPC URL for chain: xyz
Cause: Chain not in supported list. Solution:
- Use
python bridge_monitor.py chainsto see supported chains - Set custom RPC via environment variable:
{CHAIN}_RPC_URL - Check chain name spelling
RPC Connection Failed
Error: RPC connection timeout
Cause: RPC endpoint is overloaded or down. Solution:
- Set custom RPC URL via environment variable
- Try a different RPC provider
- Check if chain is experiencing issues
Comparison Errors
Route Not Supported
No bridges support ethereum → xyz
Cause: Destination chain not supported by any bridge. Solution:
- Verify destination chain exists
- Check individual bridge support with
python bridge_monitor.py detail --bridge - Consider multi-hop route
No Fee Estimates
No fee estimates available
Cause: Couldn't get fee data from any bridge. Solution:
- Check if bridges are operational
- Verify chains are supported
- Try with a different token
Common Error Patterns
| Error | Likely Cause | Quick Fix |
|---|---|---|
| Connection timeout | API overload | Retry with backoff |
| 429 Too Many Requests | Rate limited | Wait and retry |
| Bridge not found | Wrong name | Check protocols command |
| TX not found | Wrong hash/bridge | Verify hash, try all bridges |
| Chain not supported | Typo or unsupported | Check chains command |
| No estimates | Route not supported | Check bridge details |
Fallback Behavior
The system uses this fallback chain:
- Protocol API - Bridge-specific API
- DefiLlama API - Aggregated data
- On-Chain RPC - Direct blockchain verification
- Cached Data - Last known good data
- Error - If all fail
Debug Mode
Enable verbose output for troubleshooting:
python bridge_monitor.py --verbose tvl
This shows:
- API requests being made
- Response times
- Cache hits/misses
- Error details