Error Handling

The API returns standard HTTP status codes with JSON error bodies.

Error Response Format

{
  "statusCode": 400,
  "message": "Insufficient pool liquidity",
  "error": "Bad Request"
}

Common Errors

Status	Error	Cause	Solution
400	Insufficient pool liquidity	Pool doesn't have enough to fund the position	Try a smaller position or different pool
400	Leverage exceeds pool maximum	Requested leverage > pool's maxLeverage	Check offer's `maxLeverage` field
400	Invalid collateral amount	Amount is 0 or negative	Ensure positive amount in smallest units
401	Invalid API key	Key doesn't exist or is revoked	Check your `x-api-key` header
404	Position not found	Address doesn't exist in our DB	Verify the position address
429	Rate limit exceeded	Too many requests	Back off and retry after 60s
500	Internal server error	Unexpected failure	Retry with exponential backoff

Retry Strategy

For transient errors (429, 500, 502, 503):

async function apiCall(url: string, opts: RequestInit, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const res = await fetch(url, opts);
    if (res.ok) return res.json();

    if ([429, 500, 502, 503].includes(res.status)) {
      const delay = Math.min(1000 * Math.pow(2, i), 10000);
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    throw new Error(`API error: ${res.status} ${await res.text()}`);
  }
  throw new Error('Max retries exceeded');
}

Transaction Errors

When submitting signed transactions to Solana, you may encounter:

Transaction simulation failed — the on-chain state changed between quote and execution. Get a fresh quote and rebuild.
Blockhash expired — the transaction took too long. Rebuild and resubmit.
Insufficient funds — the wallet doesn't have enough SOL for rent/fees.

Always get a fresh quote immediately before building the open/close transaction to minimize stale data.