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)
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.
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)
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
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
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)
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
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
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
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
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
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)
Error Handling Pattern (Python)
Last updated
Was this helpful?

