ErrorReference

Error handling for the Flash Trade v2 API. The HTTP/transport layer behaves identically to v1; the differences are the v2-specific failure modes around the funds lifecycle (delegation, trade submission, withdrawals).

HTTP Errors (REST API Layer)

Code	Meaning	Common Cause
400	Bad Request	Invalid pubkey format, missing required field, invalid enum value, trigger/limit validation failure
404	Not Found	Account/pool not found; price symbol not in v2 config
429	Too Many Requests	Per-owner WebSocket connection limit (5) exceeded
500	Internal Server Error	Compute failure, blockhash fetch failed, unexpected state
503	Service Unavailable	Price data missing (market closed); global WebSocket limit reached

Error response formats:

// General HTTP errors (400, 404, 500, …)
{ "error": "descriptive error message" }

// Trading compute failures (returned 200 in the body)
{ "err": "descriptive error message" }

Two error keys. As in v1, the API uses "error" for HTTP-level failures and "err" for domain/compute failures returned inside a 200 body (trading endpoints). Trigger-order and limit-order builder endpoints return validation failures as 400 { "error": "…" }. Always check for both.

On-Chain Error Codes (6000–6111)

v2 executes against the v2 program (mainnet FTv2RxXarPfNta45HTTMVaGvjzsGg27FXJ3hEKWBhrzV). When a built transaction fails on-chain, your RPC returns the program log with one of the codes below. The full list (112 codes) is derived from the v2 program IDL.

Trading Errors (Most Common)

These are the errors you'll encounter most frequently when building integrations.

Code	Name	Solution
6020	MaxPriceSlippage	Price moved beyond tolerance. Widen slippagePercentage or rebuild with a fresh quote.
6021	MaxLeverage	Post-modification leverage exceeds the market max. Reduce size or add collateral first.
6022	MaxInitLeverage	New position leverage exceeds the initial-leverage cap. Reduce size or increase collateral.
6023	MinLeverage	Leverage below the minimum. Increase size or reduce collateral.
6064	MinInitLeverage	Initial leverage below the minimum. Increase size or reduce collateral.
6024	CustodyAmountLimit	Pool capacity reached. Try a smaller position or wait.
6025	PositionAmountLimit	Single position exceeds the max size. Split into smaller positions.
6031	InstructionNotAllowed	Trading paused (maintenance / circuit breaker). Wait and retry.
6032	MaxUtilization	Pool utilization at capacity. Try a smaller position or wait.
6033	CloseOnlyMode	Market in close-only mode. Only close/decrease operations allowed.
6034	MinCollateral	Below the minimum collateral. Increase collateral (use a safe buffer for TP/SL).
6087	InsufficientCollateral	Not enough collateral for the requested position.
6088	MaxPositionSize	Position size exceeds the allowed maximum.
6089	MaxExposure	Market exposure cap exceeded. Reduce size or wait.
6065	InsufficientPositionSize	Resulting position size too small (e.g. over-large partial close).
6110	InsufficientCustodyLiquidity	Not enough free liquidity in the custody. Try a smaller size or wait.
6040	CloseRatio	Invalid close amount relative to current size.

Order Errors (Limit / TP / SL)

Code	Name	Solution
6049	InvalidStopLossPrice	SL price invalid for the position direction (e.g. SL above entry for a long).
6050	InvalidTakeProfitPrice	TP price invalid for the position direction (e.g. TP below entry for a long).
6051	ExposureLimitExceeded	Market exposure cap hit. Reduce size or wait.
6052	MaxStopLossOrders	Max stop-loss orders per market reached. Cancel an existing one first.
6053	MaxTakeProfitOrders	Max take-profit orders per market reached. Cancel an existing one first.
6054	MaxOpenOrder	Max open limit orders per market reached. Cancel an existing one first.
6055	InvalidOrder	Order doesn't exist at the specified index.
6057	InvalidLimitPrice	Limit price invalid for the position direction.
6083	MaxOrdersReached	Order limit exhausted for this market+side.
6084	InvalidOrderIndex	orderId out of range (0–4).
6085	OrderNotFound	No order at the given orderId.
6086	LimitPriceNotMet	Limit price condition not met (keeper context).
6090	InvalidTriggerPrice	Trigger price invalid for the order type/direction.
6092	TriggerPriceNotMet	Trigger condition not met (keeper context).

Oracle Errors

Code	Name	Solution
6005	StaleOraclePrice	Oracle price too old. Retry after a few slots; check the equity market session.
6002	UnsupportedOracle	Internal: custody oracle misconfigured.
6003	InvalidOracleAccount	Wrong oracle account passed. Ensure the pool config is current.
6004	InvalidOracleState	Oracle feed offline or corrupted. Wait and retry.
6006	InvalidOraclePrice	Oracle returned 0 or invalid confidence. Wait and retry.
6093	InvalidPrice	Computed/derived price invalid.
6094	OracleDivergenceTooHigh	Oracle price divergence exceeds the maximum allowed.
6095	OracleConfidenceTooWide	Oracle confidence interval exceeds the maximum allowed.
6035	PermissionlessOracleMissingSignature	Keeper/oracle authority error (missing Ed25519 verify instruction).
6036	PermissionlessOracleMalformedEd25519Data	Internal oracle signature-data error.
6037	PermissionlessOracleSignerMismatch	Oracle update not signed by the oracle authority.
6038	PermissionlessOracleMessageMismatch	Signed message doesn't match instruction params.
6096	StaleBackupOraclePrice	Backup oracle price too stale.
6097	InvalidBackupOracleSignature	Invalid backup oracle Ed25519 signature.

Pyth Lazer Errors

Code	Name	Notes
6098	InvalidLazerMessage	Pyth Lazer oracle message format error
6099	InvalidLazerPayload	Pyth Lazer payload parsing failure
6100	InvalidLazerChannel	Wrong Lazer channel for this custody
6101	InvalidLazerTimestamp	Lazer message too old or in the future

Deposit / Withdrawal / Balance (v2 funds lifecycle)

Code	Name	Solution
6078	InsufficientBalance	Insufficient balance for the operation.
6079	InsufficientAvailableBalance	Insufficient available balance (deposits minus obligations).
6075	NoDepositsToClaim	No deposits available to claim.
6076	PendingDepositNotClaimed	Pending deposit hasn't been claimed yet.
6077	NoWithdrawalPending	No pending withdrawal to execute (nothing for execute-withdrawal to resume).
6048	MaxDepostsReached	Token vault deposit limit hit.
6058	MinReserve	Custody minimum-reserve threshold. Pool must maintain reserves.
6059	MaxWithdrawTokenRequest	Max pending withdraw requests reached.
6108	UserDepositDisabled	User deposits are currently disabled by the protocol.
6109	UserWithdrawDisabled	User withdrawals are currently disabled by the protocol.

Liquidity / LP

Code	Name	Solution
6026	TokenRatioOutOfRange	LP op pushes allocation outside min/max ratios.
6041	InsufficientStakeAmount	Trying to unstake more LP than staked.
6060	InvalidRewardDistribution	Admin reward-distribution error.
6061	LpPriceOutOfBounds	LP price outside safety bounds (pool safety mechanism).
6062	InsufficientRebateReserves	Rebate vault insufficient balance.
6067	AlreadyMinted	LP tokens already minted for this deposit.
6068	NoLpTokensToMint	No LP tokens to mint — run addLiquidityEr first.
6080	InvalidLpTokenAccount	Invalid LP token account.
6081	InvalidDepositReceipt	Invalid deposit-receipt account.
6103	LiquidityAddDisabled	Liquidity add is currently disabled.
6104	LiquidityRemoveDisabled	Liquidity remove is currently disabled.

Access, Authority & Delegation

Code	Name	Solution
6102	Unauthorized	Signer is not the owner or an authorized delegate.
6056	InvalidAuthority	Wrong authority for the instruction.
6045	InvalidOwner	Token account owner mismatch. Ensure the ATA is derived correctly.
6046	InvalidAccess	Pool requires NFT/referral access.
6047	TokenStakeAccountMismatch	Referral account linked to the wrong stake account.
6111	InvalidValidatorKey	Delegation key is invalid.
6105	TradeInitDisabled	Opening/increasing positions is currently disabled.
6106	TradeMaintDisabled	Position maintenance (modify) is currently disabled.
6107	TradeLiquidationDisabled	Liquidations are currently disabled.

State Validation

Code	Name	Solution
6007	InvalidEnvironment	Test-only instruction called on mainnet.
6008	InvalidPlatformState	Platform account corrupted/uninitialized.
6009	InvalidPoolState	Pool account corrupted/uninitialized. Verify the pool address.
6010	InvalidCustodyState	Custody account issue. Re-fetch the pool config.
6011	InvalidMarketState	Market account issue. Verify the market exists for this pool/side.
6012	InvalidCollateralCustody	Wrong collateral token for this market.
6013	InvalidPositionState	Position doesn't exist or is already closed.
6014	InvalidDispensingCustody	Internal custody routing error.
6015	InvalidPerpetualsConfig	Global config issue.
6016	InvalidPoolConfig	Pool parameters invalid.
6017	InvalidCustodyConfig	Custody parameters invalid.
6018	InvalidBasketState	Basket account corrupted, not initialized, or not delegated.
6071	InvalidPoolAccount	Pool account failed PDA validation.
6072	InvalidCustodyAccount	Custody account failed PDA validation.
6069	InvalidCustodyTokenAccount	Custody token account mismatch.
6070	InvalidTokenMint	Token mint mismatch for the operation.
6074	InvalidAccountData	Account data failed to deserialize/validate.

Token / Pool / Market Support

Code	Name	Solution
6027	UnsupportedToken	Token mint not recognized by the pool.
6028	UnsupportedCustody	Custody not found in the pool.
6029	UnsupportedPool	Pool address invalid.
6030	UnsupportedMarket	Market doesn't exist for this target/collateral/side.

Arithmetic & Misc

Code	Name	Notes
6001	MathOverflow	Arithmetic overflow. Rare — extreme sizes/prices.
6039	ExponentMismatch	Internal price-calculation error (operand exponents).
6019	InsufficientAmountReturned	Output below minimum.
6042	InvalidFeeDeltas	Internal fee-calculation error.
6043	InvalidFeeDistributionCustody	Internal custody routing.
6044	InvalidCollection	NFT collection not recognized.
6066	InsufficientLockedAmount	Not enough locked amount for the operation.
6073	InvalidAmount	Amount is zero or otherwise invalid.
6063	InvalidInput	Generic invalid input parameter.
6091	InvalidArgument	Generic invalid argument.
6000	CustomError	Generic custom error (catch-all).

v2-Specific Scenarios & Recovery

Wrong RPC for the transaction

Account & funds transactions (init-*, deposit-direct, delegate-basket, request-withdrawal, execute-withdrawal) and trading transactions (all trading endpoints) submit to different RPC endpoints. Submitting one to the wrong RPC fails. Route account & funds transactions to your Solana RPC and trading transactions to the v2 RPC.

"Basket not delegated" / trade rejected

A trade was submitted before the basket was delegated, or while it was undelegated. Ensure delegate-basket has confirmed and the basket is currently delegated.

Trade fails with insufficient collateral despite a deposit

deposit-direct submits to your Solana RPC; its funds must be confirmed (and credited to the deposit ledger) before they're usable for trades. Confirm the deposit first.

Withdrawal funds didn't arrive

request-withdrawal starts the withdrawal and closes the withdrawal escrow once funds are released. If the escrow hasn't closed after a reasonable wait, the withdrawal didn't complete automatically — call execute-withdrawal to finish it in a single transaction. Set includeCustodySettlement based on whether the custody settlement receipt is still on-chain and owned by the program.

Withdrawal builder fails on custody settlement

If includeCustodySettlement: true but the settlement receipt already exists (created by a prior step), the extra settlement instruction can conflict. Retry with includeCustodySettlement: false. Conversely, if it's false but the receipt doesn't exist yet, the withdrawal can't settle — set it true.

SOL withdrawn but balance unchanged

Withdrawn SOL arrives as WSOL in your associated token account. Unwrap the WSOL ATA back to native SOL after the withdrawal completes.

"Blockhash not found" / "Blockhash expired"

Built transactions embed a blockhash that expires in ~45s. Rebuild via the endpoint and submit immediately. The v2 trading endpoints refresh the blockhash between calls to avoid duplicate-hash collisions on back-to-back builds.

Position not reflected immediately

Read position/order state from the basket snapshot (GET /v2/owner/{owner} or the WebSocket), not from the trade response. The snapshot updates when the basket account changes on-chain; there can be brief lag between submitting a v2 transaction and the committed state appearing.

Error Handling Pattern (TypeScript)

try {
  const response = await fetch(`${FLASH_API_URL}/v2/transaction-builder/open-position`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  });

  if (!response.ok) {
    const { error } = await response.json();
    if (response.status === 404) console.error("Market or symbol not found");
    if (response.status === 503) console.error("Price data unavailable (market closed?)");
    throw new Error(error);
  }

  const data = await response.json();
  if (data.err) {
    // Compute error returned in a 200 body
    console.error("Builder error:", data.err);
  } else if (data.transactionBase64) {
    // Sign and submit — to the v2 RPC for trades, Solana RPC for account/funds ops
  }
} catch (err) {
  console.error("Request failed:", err.message);
}

Error Handling Pattern (Python)

import requests

try:
    r = requests.post(f"{FLASH_API_URL}/v2/transaction-builder/open-position", json=request)
    r.raise_for_status()
    data = r.json()
    if data.get("err"):
        print(f"Builder error: {data['err']}")
    elif data.get("transactionBase64"):
        print("Transaction ready to sign")
except requests.exceptions.HTTPError as e:
    body = e.response.json()
    print(f"API error ({e.response.status_code}): {body.get('error', 'Unknown')}")
except requests.exceptions.ConnectionError:
    print("Cannot reach Flash Trade API")