Error Handling

Handle trading errors with PerpsError and error codes

Trading operations may throw PerpsError with numeric error codes. Use PerpsErrorCode for type-safe handling:

import { PerpsError, PerpsErrorCode } from '@lifi/perps-sdk';

try {
  await perps.placeOrder({
    address: userAddress,
    provider: 'hyperliquid',
    market: { marketId: 'BTC', categoryId: 'hyperliquid' },
    side: 'BUY',
    type: 'MARKET',
    size: '0.1',
    price: '95500.00',
  });
} catch (error) {
  if (error instanceof PerpsError) {
    switch (error.code) {
      case PerpsErrorCode.InsufficientMargin:  // 2021
        console.error('Not enough margin. Reduce size or add funds.');
        break;
      case PerpsErrorCode.InsufficientBalance: // 2022
        console.error('Insufficient balance. Deposit more funds.');
        break;
      case PerpsErrorCode.MarketNotFound:      // 2023
        console.error('Invalid asset. Check available assets.');
        break;
      case PerpsErrorCode.AgentUnauthorized:   // 2011
        console.error('Agent not authorized. Complete authorization flow.');
        break;
      case PerpsErrorCode.NonceExpired:        // 2042
        console.error('Payload expired. Retry the operation.');
        break;
      default:
        console.error(`Error ${error.code}: ${error.message}`);
    }
  }
}

SDK-originated messages

PerpsErrorMessage pairs canonical human-readable text with PerpsErrors the SDK itself raises (not the backend’s error responses): AgentNotFound (agent-signing setup incomplete) and AgentStorageCorrupt (a stored agent keypair is malformed and the agent must be revoked and re-approved).

Common Trading Errors

Code	Name	Cause
2021	InsufficientMargin	Not enough margin for order size/leverage
2022	InsufficientBalance	Account lacks funds
2020	ExchangeRejected	DEX rejected (invalid params, market closed)
2024	OrderNotFound	Order ID doesn’t exist or already filled
2042	NonceExpired	Payload TTL exceeded — retry operation

See Error Codes for the complete reference, including how errorCodeFromStatus resolves a code from an HTTP status.