openocean-finance OpenOcean Error Handling Skill
Handle errors and exceptions that occur during OpenOcean swap operations. This skill provides troubleshooting guidance, recovery steps, and fallback strategies.
When to Use This Skill
Use this skill when:
- Any OpenOcean API call returns a
codeother than200 - Token resolution fails (symbol not found)
- Transaction execution fails (
cast senderrors) - Network connectivity issues
- Unexpected response formats
- Rate limiting or quota exceeded
Error Categories
Category 1: API Errors (HTTP/JSON)
| Code | Meaning | Common Causes | Recovery Steps |
|---|---|---|---|
| 200 | Success | None | Continue normally |
| 400 | Bad Request | Invalid parameters, wrong format | 1. Check parameter formats2. Verify token addresses3. Ensure amount is in wei |
| 401 | Unauthorized | Missing/invalid API key | 1. Check API key configuration2. Contact OpenOcean support |
| 403 | Forbidden | Access denied | 1. Check permissions2. Verify chain support |
| 404 | Not Found | Endpoint or resource not found | 1. Check URL path2. Verify chain slug |
| 429 | Rate Limited | Too many requests | 1. Wait 10-30 seconds2. Implement exponential backoff3. Consider enterprise plan |
| 500 | Internal Server Error | OpenOcean server issue | 1. Retry after 30 seconds2. Check OpenOcean status page3. Try alternative chain |
| 502/503/504 | Gateway/Service Unavailable | Network or service issues | 1. Wait and retry2. Check network connectivity3. Try different RPC endpoint |
Category 2: Business Logic Errors
| Error Pattern | Meaning | Recovery Steps |
|---|---|---|
"code": 200, "data": null |
No route found | 1. Check token pair liquidity2. Try different amount3. Use different chain |
"code": 200, "data": {..., "outAmount": "0"} |
Zero output amount | 1. Check token decimals2. Verify amount is sufficient3. Try larger amount |
| Invalid token address | Token not recognized | 1. Verify contract address2. Check chain compatibility3. Use token list API |
Category 3: Token Resolution Errors
| Error | Cause | Recovery |
|---|---|---|
| Symbol not found in registry | Token not in reference list | 1. Use OpenOcean token API2. Ask user for address3. Check alternative symbols |
| Multiple matches found | Ambiguous symbol | 1. Show options to user2. Use market cap ranking3. Ask user to specify address |
| Invalid chain for token | Token not deployed on chain | 1. Check token deployment2. Suggest alternative chain3. Use bridge if available |
Category 4: Transaction Execution Errors
| Error Message | Meaning | Recovery Steps |
|---|---|---|
insufficient funds for gas * price + value |
Not enough native token | 1. Add funds to wallet2. Reduce swap amount3. Use lower gas price |
execution reverted: OpenOcean: insufficient output amount |
Price moved beyond slippage | 1. Increase slippage tolerance2. Wait for better price3. Try smaller amount |
execution reverted: ERC20: transfer amount exceeds allowance |
Token not approved | 1. Approve token first2. Check approval amount3. Reset approval if needed |
nonce too low / nonce too high |
Nonce mismatch | 1. Let wallet manage nonces2. Check pending transactions3. Use higher nonce |
transaction underpriced |
Gas price too low | 1. Increase gas price2. Use current market rate3. Wait for less congestion |
replacement transaction underpriced |
Competing transaction | 1. Use significantly higher gas2. Cancel pending transaction3. Wait for confirmation |
Recovery Workflows
Workflow 1: API Error Recovery
1. Check error code and message
2. If 429 (rate limited):
- Wait 10 seconds
- Retry once
- If still failing, suggest waiting longer
3. If 400 (bad request):
- Validate all parameters
- Check token addresses
- Verify amount format
4. If 500 (server error):
- Wait 30 seconds
- Retry once
- Suggest trying later
5. If persistent:
- Suggest alternative DEX
- Try different chain
- Contact OpenOcean support
Workflow 2: Token Resolution Recovery
1. Symbol not found:
- Query OpenOcean token API
- If found, use it
- If not found, ask user for address
2. Multiple matches:
- Show top 3 by market cap
- Ask user to choose
- Suggest verifying on explorer
3. Invalid address:
- Verify on block explorer
- Check chain compatibility
- Suggest correct address
Workflow 3: Transaction Execution Recovery
1. Insufficient funds:
- Calculate required amount
- Suggest adding funds
- Offer to reduce swap size
2. Insufficient allowance:
- Provide approval transaction
- Suggest approval amount
- Explain approval process
3. Slippage exceeded:
- Show current price vs quote
- Suggest higher slippage
- Offer to requote
4. Gas issues:
- Check current gas prices
- Suggest appropriate gas
- Offer to wait for better conditions
User Communication
Good Error Messages
Bad: "Error: 400" Good: "The API returned error 400 (Bad Request). This usually means one of the parameters is invalid. Let me check: are you sure the token addresses are correct for this chain?"
Bad: "Transaction failed" Good: "The transaction failed with error: 'insufficient funds for gas * price + value'. You need at least 0.01 ETH for gas plus the swap value, but the current balance is only 0.005 ETH."
Actionable Suggestions
Always provide:
- What happened — Clear error description
- Why it happened — Probable cause
- How to fix — Specific steps
- Alternative options — Workarounds
Fallback Strategies
Primary Fallback: Parameter Adjustment
- Reduce amount
- Increase slippage
- Use different gas price
- Try different chain
Secondary Fallback: Alternative Service
If OpenOcean consistently fails:
- Suggest other aggregators (1inch, Paraswap)
- Direct DEX access (Uniswap, PancakeSwap)
- Manual swap via wallet interface
Tertiary Fallback: Manual Intervention
When automation fails:
- Provide manual steps
- Suggest waiting and retrying later
- Recommend contacting support
Monitoring and Logging
What to Log
- API calls — URL, parameters, response code
- Token resolutions — Symbol, address, chain
- Transaction attempts — Hash, status, gas used
- Errors — Full error object, timestamp
Alert Thresholds
- Warning: 3 consecutive API errors
- Critical: 10+ errors in 5 minutes
- Stop: Balance below minimum for gas
Testing Error Scenarios
Test these scenarios regularly:
- Invalid token — Non-existent symbol
- Insufficient balance — Ask for more than available
- High slippage — Extreme price movement
- Network outage — RPC endpoint down
- Rate limiting — Rapid consecutive calls
Prevention Tips
Before Swap
- Validate all inputs — tokens, amounts, addresses
- Check balances — token + gas
- Verify approvals — ERC-20 allowances
- Monitor gas — current market rates
During Swap
- Set reasonable timeouts — 30 seconds for API, 2 minutes for tx
- Implement retry logic — with exponential backoff
- Monitor progress — confirm each step
After Swap
- Verify outcome — check balances, tx status
- Log results — for analysis and debugging
- Update state — mark as complete/failed
Support Resources
OpenOcean Resources
- API Documentation: https://apis.openocean.finance/
- Status Page: Check for service outages
- Support: Telegram/Discord channels
- GitHub: Issue tracker for bugs
Community Resources
- Block Explorers: Etherscan, BscScan, etc.
- Gas Trackers: ETH Gas Station, GasNow
- Token Verifiers: TokenSniffer, RugDoc
Emergency Contacts
For critical issues involving fund loss:
- Immediate: Stop all automated trading
- Investigation: Check transaction on explorer
- Support: Contact OpenOcean with tx hash
- Community: Seek help in relevant channels
Remember: Most errors are recoverable with proper handling. Stay calm, follow the recovery workflows, and prioritize user fund safety above all else.