Error Handling

All API calls return Result<T, ErrorCode> types.

Error Structure

type ErrorCode = variant {
  AccountError: AccountError;
  AssetError: AssetError;
  TradingError: TradingError;
  WalletError: WalletError;
  SystemError: SystemError;
  GuardError: GuardError;
  InternalError: text;
};

Trading Errors

Error	Description
MarketNotFound	Invalid market_id
OrderNotFound	Order doesn't exist
InvalidPrice	Price is zero or invalid
InvalidQuantity	Quantity is zero or invalid
ValidationFailed	Order validation failed
MarketAlreadyExists	Market already registered
SettlementFailed	Settlement processing failed
Unauthorized	Not authorized for this operation
OrderBookError	Matching engine errors

OrderBook Errors

Error	Description
MarketClosed	Market is paused
OrderNotFound	Order not in book
OrderAlreadyExists	Duplicate order ID
SelfTradeDetected	Self-trade prevention triggered
InsufficientLiquidity	Not enough liquidity for market order
RiskLimitExceeded	Order exceeds risk limits
ValidationError	Order validation failed

Wallet Errors

Error	Description
InsufficientBalance	Not enough available funds
InvalidAddress	Invalid withdrawal address
InvalidAmount	Amount out of valid range
InvalidWithdrawalAmount	Outside min/max limits
UnsupportedAsset	Asset not supported
WithdrawalNotFound	Withdrawal ID not found
TooManyPendingWithdrawals	Rate limit exceeded
ArithmeticOverflow	Calculation overflow

System Errors

Error	Description
AnonymousCaller	Anonymous principal not allowed
Unauthorized	Not authorized
NotController	Controller access required
NotAllowlisted	Principal not in allowlist
UnderMaintenance	System in maintenance mode
RateLimitExceeded	Too many requests
ConcurrentLimitExceeded	Too many concurrent operations

TypeScript Error Handling

try {
  const response = await backend.place_order(orderRequest)

  if ('Ok' in response) {
    console.log('Order placed:', response.Ok.order_id)
  } else {
    const error = response.Err

    if ('TradingError' in error) {
      const tradingError = error.TradingError

      if ('InsufficientBalance' in tradingError) {
        console.error('Not enough funds')
      } else if ('MarketNotFound' in tradingError) {
        console.error('Invalid market')
      } else if ('OrderBookError' in tradingError) {
        const obError = tradingError.OrderBookError
        if ('SelfTradeDetected' in obError) {
          console.error('Order would trade against yourself')
        }
      }
    } else if ('SystemError' in error) {
      const sysError = error.SystemError

      if ('RateLimitExceeded' in sysError) {
        const { limit, window_seconds } = sysError.RateLimitExceeded
        console.error(`Rate limited: ${limit} requests per ${window_seconds}s`)
      } else if ('UnderMaintenance' in sysError) {
        console.error('System is under maintenance')
      }
    } else if ('WalletError' in error) {
      if ('InsufficientBalance' in error.WalletError) {
        console.error('Insufficient balance')
      }
    }
  }
} catch (error) {
  // Network error or other unexpected error
  console.error('Network error:', error)
}

SDK Error Handling

Using the @vortum/sdk:

import { OnexError } from '@vortum/sdk'

try {
  await client.trading.placeOrder(request)
} catch (error) {
  if (error instanceof OnexError) {
    if (error.isTradingError('InsufficientBalance')) {
      // Handle insufficient balance
    } else if (error.isSystemError('RateLimitExceeded')) {
      // Handle rate limit
    } else if (error.isWalletError('InvalidAddress')) {
      // Handle invalid address
    }

    // Get error details
    console.error(error.message)
    console.error(error.code)
  }
}

Best Practices

1. Always check for errors - Don't assume success
2. Handle specific errors - Provide appropriate user feedback
3. Retry transient errors - Rate limits, network issues
4. Log unexpected errors - For debugging
5. Don't expose internal errors - Show user-friendly messages