Error Playbooks

// Example handling
if (error.status === 400) {
  console.error('Bad request:', error.message);
  // Parse error message for specific field
  // Don't retry - fix parameters
}

if (['quote', 'routes'].includes(operation) && error.code === 1002) {
  // Suggest alternatives
  const suggestions = [
    'Try a smaller amount',
    'Try a different destination token',
    'Use USDC or ETH as intermediate'
  ];
}

// Reuse this parser in the error-handling template below.
function parseRetryAfter(header, now = Date.now()) {
  if (typeof header !== 'string') return undefined;
  const value = header.trim();
  if (/^\d+$/.test(value)) {
    const delayMs = Number(value) * 1000;
    return Number.isSafeInteger(delayMs) ? delayMs : undefined;
  }
  if (/GMT$/.test(value) && Number.isFinite(Date.parse(value))) {
    return Math.max(0, Date.parse(value) - now);
  }
  return undefined;
}

async function handleRateLimit(error, attempt) {
  // The adapter supplies the Retry-After header as error.retryAfter.
  const waitTime = parseRetryAfter(error.retryAfter)
    ?? Math.min(Math.pow(2, attempt) * 1000, 30000);
  console.log(`Rate limited. Waiting ${waitTime}ms...`);
  await sleep(waitTime);
}

// Usage in retry loop
for (let attempt = 0; attempt < 5; attempt++) {
  try {
    return await fetchQuote(params);
  } catch (error) {
    if (error.status === 429 && attempt < 4) {
      await handleRateLimit(error, attempt);
      continue;
    }
    throw error;
  }
}

if (error.status >= 500) {
  await sleep(2000);
  // Retry once
  return await fetchQuote(params);
}

if (error.code === 'NO_POSSIBLE_ROUTE') {
  return {
    error: 'No route available',
    suggestions: [
      'Try USDC or USDT as the destination token',
      'Try a smaller amount',
      'Check if both chains support the tokens'
    ]
  };
}

if (error.code === 'AMOUNT_TOO_LOW') {
  // Error often includes minimum amount
  const minAmount = error.minAmount || 'unknown';
  return {
    error: `Minimum amount required: ${minAmount}`,
    action: 'Increase transfer amount'
  };
}

if (error.code === 1007 || error.message?.includes('slippage')) {
  // Offer to increase slippage
  const currentSlippage = params.slippage || 0.005;
  const suggestedSlippage = Math.min(currentSlippage * 2, 0.03);
  
  return {
    error: 'Slippage exceeded',
    currentSlippage: `${currentSlippage * 100}%`,
    suggestedSlippage: `${suggestedSlippage * 100}%`,
    action: 'Retry with higher slippage or smaller amount'
  };
}

if (error.code === 'CHAIN_NOT_SUPPORTED') {
  // Fetch supported chains
  const chains = await getChains();
  return {
    error: 'Chain not supported',
    supportedChains: chains.map(c => ({ id: c.id, name: c.name }))
  };
}

if (error.message.includes('reverted')) {
  // Quote expired or conditions changed
  console.log('Transaction reverted. Fetching new quote...');
  const newQuote = await getQuote(originalParams);
  // Retry with new quote
}

if (error.message.includes('insufficient funds')) {
  return {
    error: 'Insufficient balance',
    required: {
      token: quote.action.fromAmount,
      gas: 'Plus gas fees in native token'
    }
  };
}

async function handleLiFiError(error, params, operation) {
  // operation: 'status' | 'quote' | 'routes' for reads, anything else (e.g. 'submit') for writes.
  if (typeof operation !== 'string') {
    throw new TypeError('operation is required, e.g. "status", "quote", "routes" or "submit"');
  }
  // Only read-only discovery and polling may be retried automatically.
  const isRead = ['status', 'quote', 'routes'].includes(operation);
  // HTTP status and API error code are different namespaces.
  const code = error.status;
  if (operation === 'status' && (code === 404 || (code === 200 && error.statusValue === 'NOT_FOUND'))) {
    return { retry: true, action: 'poll_then_reconcile', resubmit: false, message: 'Outcome unknown; do not resend' };
  }
  if (code === 401 || code === 403) {
    return { retry: false, action: 'check_credentials', message: 'Check API key and access' };
  }
  
  // Rate limiting
  if (code === 429) {
    const header = error.retryAfter; // adapter supplies the Retry-After header, if present
    const delayMs = parseRetryAfter(header); // shared helper from the rate-limit example above
    if (!isRead) {
      return { retry: false, resubmit: false, delayMs, action: 'reconcile', message: 'Rate limited; reconcile before any resubmission' };
    }
    return { retry: true, wait: true, delayMs, message: 'Rate limited' };
  }
  
  // Server errors
  if (code >= 500) {
    if (!isRead) {
      return { retry: false, resubmit: false, action: 'reconcile', message: 'Server error; outcome unknown, reconcile before any resubmission' };
    }
    return { retry: true, message: 'Server error' };
  }
  
  // No route (NoQuoteError = 1002)
  if (['quote', 'routes'].includes(operation) && (error.code === 1002 || error.code === 'NO_POSSIBLE_ROUTE')) {
    return {
      retry: false,
      message: 'No route found',
      suggestions: getRouteSuggestions(params)
    };
  }
  
  if (code === 404) {
    return { retry: false, action: 'check_endpoint', message: 'Resource not found; check endpoint and response body' };
  }

  // Amount issues
  if (error.code === 'AMOUNT_TOO_LOW') {
    return {
      retry: false,
      message: `Amount too low. Minimum: ${error.minAmount}`,
      action: 'increase_amount'
    };
  }
  
  // Slippage
  if (error.code === 1007 || error.message?.includes('slippage')) {
    return {
      retry: false,
      requiresUserApproval: true,
      suggestedParam: { slippage: params.slippage * 2 },
      message: 'Consider increasing slippage'
    };
  }
  
  // Default
  return {
    retry: false,
    message: error.message || 'Unknown error'
  };
}

function getRouteSuggestions(params) {
  return [
    'Try USDC, USDT, or ETH instead',
    'Try a smaller amount',
    'Check if tokens are supported on both chains'
  ];
}