> For the complete documentation index, see [llms.txt](https://docs.flash.trade/flash-trade/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.trade/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/errorreference.md).

# 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:**

```json
// 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)

```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)

```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")
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flash.trade/flash-trade/flash-trade-protocol/build-on-flash/flash-trade-api/flash-trade-v2/errorreference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.