Vulcan Error Recovery

vulcan-error-recovery

Use this skill for:

• Routing errors by category
• Recovering from failed on-chain transactions
• Handling network and rate limit errors

Error Envelope Format

{
  "ok": false,
  "error": {
    "category": "validation",
    "code": "UNKNOWN_MARKET",
    "message": "Market not found",
    "retryable": false
  }
}

Category Routing Table

tx_failed Recovery (Critical)

On-chain transactions can fail in complex ways. Never blind-retry.

1. Check position state first:

   vulcan_position_list → {}
   vulcan_margin_status → {}
   

2. Common causes:

   • Blockhash expired — transaction took too long. Safe to retry with fresh state.
   • Insufficient SOL for fees — check vulcan_wallet_balance.
   • Account state changed — another transaction modified the account between build and send.
   • Slippage exceeded — market moved. Re-check price and retry.

3. Recovery pattern:

   1. vulcan_position_list → {}           # did the original tx partially succeed?
   2. vulcan_margin_status → {}           # is collateral state as expected?
   3. vulcan_wallet_balance → {}          # enough SOL for fees?
   4. vulcan_market_ticker → { symbol }   # has price moved significantly?
   5. Re-attempt the operation if state is clean
   

Network Error Recovery

1. Wait 1 second
2. Retry the same call
3. If still failing, wait 2 seconds and retry
4. After 3 failures, check connectivity: vulcan_status → {}
5. Report to user if API is down

Common Error Codes and Fixes