Error Codes

Complete reference of Seesaw protocol error codes.

Overview

Error codes are organized by category for easy identification:

Market Errors (0x1001 - 0x100F)

Market Error Examples

// Check if market exists before interacting
try {
  const market = await program.account.market.fetch(marketPda);
} catch (e) {
  if (e.code === 0x1001) {
    console.log('Market not yet created, waiting...');
  }
}

// Handle trading state
if (error.code === 0x1005) {
  console.log('Trading has ended for this market');
  // Redirect to settlement or next market
}

Oracle Errors (0x2001 - 0x2008)

Oracle Error Examples

// Handle stale oracle
if (error.code === 0x2004) {
  console.log('Oracle price is stale, retrying in 1 second...');
  await sleep(1000);
  // Retry operation
}

// Handle confidence issues
if (error.code === 0x2006) {
  console.log('Price confidence too wide, market may be volatile');
  // Consider waiting for better conditions
}

Order Errors (0x3001 - 0x300B)

Order Error Examples

// Handle insufficient collateral
if (error.code === 0x3002) {
  const required = calculateCollateral(price, quantity);
  console.log(`Need ${required} USDC to place this order`);
  // Prompt user to deposit
}

// Handle PostOnly rejection
if (error.code === 0x3006) {
  console.log('Your PostOnly order would match immediately');
  // Either adjust price or switch to Limit
}

// Handle order not found
if (error.code === 0x3005) {
  console.log('Order not found - may have been filled');
  // Refresh order book state
}

Math Errors (0x4001)

Math Error Example

// This typically indicates a bug or extreme values
if (error.code === 0x4001) {
  console.error('Math overflow detected - this should not happen');
  console.error('Check your input values:', { price, quantity });
  // Report as bug if values are reasonable
}

Account Errors (0x5001 - 0x5007)

Account Error Examples

// Handle PDA derivation errors
if (error.code === 0x5003) {
  // Verify PDA derivation
  const [expectedPda] = PublicKey.findProgramAddressSync(
    [Buffer.from('seesaw'), Buffer.from('market'), marketIdBuffer],
    programId
  );
  console.log('Expected PDA:', expectedPda.toString());
}

// Handle insolvency (critical)
if (error.code === 0x5006) {
  console.error('CRITICAL: Insolvency detected - contact support immediately');
  // This indicates a protocol-level issue
}

Position Errors (0x6001 - 0x6002)

Position Error Examples

// Handle protocol pause
if (error.code === 0x6002) {
  console.log('Protocol is currently paused');
  // Check announcements for more info
}

Token Architecture Errors (0x7001 - 0x7006)

Token Error Examples

// Handle losing position redemption attempt
if (error.code === 0x7005) {
  console.log('These shares did not win - payout is 0');
}

// Handle active market check
if (error.code === 0x7002) {
  console.log('A market already exists for this epoch');
  // Fetch and use existing market
}

Error Handling Best Practices

TypeScript Error Handler

function handleSeesawError(error: any): string {
  const code = error.code || error.error?.code;

  const errorMessages: Record<number, string> = {
    0x1001: 'Market not found - it may not be created yet',
    0x1003: 'Invalid market state for this operation',
    0x1005: 'Trading has ended for this market',
    0x2004: 'Oracle price is stale - try again shortly',
    0x3002: 'Insufficient USDC balance for this order',
    0x3003: 'Insufficient shares to sell',
    0x3006: 'PostOnly order would match - adjust price',
    // Add more as needed
  };

  return errorMessages[code] || `Unknown error: ${code}`;
}

Retry Logic

async function withRetry<T>(
  fn: () => Promise<T>,
  options: { maxRetries: number; retryableErrors: number[] }
): Promise<T> {
  let lastError: any;

  for (let i = 0; i < options.maxRetries; i++) {
    try {
      return await fn();
    } catch (e: any) {
      lastError = e;

      if (!options.retryableErrors.includes(e.code)) {
        throw e;
      }

      await sleep(1000 * Math.pow(2, i));
    }
  }

  throw lastError;
}

// Use with oracle errors
await withRetry(() => snapshotPrice(market), {
  maxRetries: 5,
  retryableErrors: [0x2004], // StaleOracle
});

Error Code Quick Reference

MARKET (0x10xx)           ORACLE (0x20xx)           ORDER (0x30xx)
├─ 0x1001 NotFound        ├─ 0x2001 InvalidOwner    ├─ 0x3001 InvalidQty
├─ 0x1002 Exists          ├─ 0x2002 InvalidFeed     ├─ 0x3002 NoCollateral
├─ 0x1003 InvalidState    ├─ 0x2003 Mismatch        ├─ 0x3003 NoShares
├─ 0x1004 NotStarted      ├─ 0x2004 Stale           ├─ 0x3004 BookFull
├─ 0x1005 Ended           ├─ 0x2005 InvalidPrice    ├─ 0x3005 NotFound
├─ 0x1006 Snapshotted     ├─ 0x2006 WideConf        ├─ 0x3006 WouldCross
├─ 0x1007 Resolved        ├─ 0x2007 NotTrading      ├─ 0x3007 Settled
├─ 0x1008 NotResolved     └─ 0x2008 FeedIdMismatch  ├─ 0x3008 NoPosition
├─ 0x1009 Closed                                    ├─ 0x3009 PriceLow
├─ 0x100A Expired         MATH (0x40xx)             ├─ 0x300A PriceHigh
├─ 0x100B TooEarly        └─ 0x4001 Overflow        └─ 0x300B CollateralLow
├─ 0x100C EpochNotStart
├─ 0x100D EpochNotEnd     ACCOUNT (0x50xx)          POSITION (0x60xx)
├─ 0x100E NotOwner        ├─ 0x5001 InvalidType     ├─ 0x6001 LimitExceeded
└─ 0x100F PositionsLeft   ├─ 0x5002 InvalidOwner    └─ 0x6002 Paused
                          ├─ 0x5003 InvalidPDA
                          ├─ 0x5004 Initialized     TOKEN (0x70xx)
                          ├─ 0x5005 NoRent          ├─ 0x7001 NotImpl
                          ├─ 0x5006 Insolvent       ├─ 0x7002 ActiveExists
                          └─ 0x5007 IdOverflow      ├─ 0x7003 CantExpire
                                                    ├─ 0x7004 InvalidToken
                                                    ├─ 0x7005 InvalidRedeem
                                                    └─ 0x7006 VaultMismatch

Next Steps

• Review Constants for protocol values
• See Glossary for terminology