Common Errors

This guide lists common errors you might encounter when using the SDK or API, along with their causes and recommended solutions.

Error Reference

Error Subject	Error Messages / Codes	Description & Solution
Insufficient Funds	`insufficient lamports`, `BALANCE_INSUFFICIENT`, `BANKRUPTCY_INSUFFICIENT_COVERAGE`	Cause: Wallet lacks enough SOL for transaction fees or USDC/tokens for the trade. Solution: Deposit more funds to cover fees and order value.
Session & Auth	`SESSION_NOT_FOUND`, `INVALID_SIGNATURE`	Cause: The trading session key has expired, is invalid, or the signature failed. Solution: Refresh the session or disconnect and reconnect your wallet to generate a new session.
Order Validation	`ORDER_EXECUTION_LIMIT_PRICE`, `ORDER_EXECUTION_SIZE_LIMIT`, `tick size`, `precision`	Cause: Price or size does not meet market precision requirements. Solution: Adjust values to match the market’s tick size and lot size.
Market Constraints	`POST_ONLY_MUST_NOT_FILL_ANY_OPPOSITE_ORDERS`, `IMMEDIATE_ORDER_GOT_NO_FILLS`, `ORDER_EXECUTION_FILL_OR_KILL`	Cause: Order constraints (Post-Only, IOC, FOK) could not be satisfied. Solution: Relax constraints or adjust price/size to ensure execution.
Market Status	`MARKET_NOT_READY`, `MARKET_FROZEN`	Cause: The market is currently closed or frozen. Solution: Wait for the market to resume trading.
Position Limits	`POSITION_SIZE_LIMIT`, `REDUCE_ONLY`, `POSITION_STATE_ORDER_SIZE`, `position size`	Cause: Position limit reached, or a reduce-only order would increase or flip the position. For perps, reduce-only supports all fill modes (Limit, PostOnly, IOC, FOK). Resting reduce-only orders are automatically shrunk or cancelled (worst price first) if total contra exposure exceeds position size. Solution: Reduce trade size or ensure the order only closes existing positions.
Stale Data	`TIMESTAMP_STALE`, `TIMESTAMP_OUT_OF_THRESHOLD`, `price changed`	Cause: Market data used for the order is too old. Solution: Fetch fresh market data and retry the order.
Account Health	`UNHEALTHY`, `OMF`	Cause: Order would put account in an unhealthy state or exceed risk parameters. Solution: Reduce order size or add more margin to your account.
Order Execution	`ORDER_EXECUTION_EMPTY`	Cause: Market has insufficient liquidity to fill the order. Solution: Try a smaller order size or wait for more orderbook liquidity.
Minimum Size	`minimum size`, `MINIMUM_SIZE_DECIMALS`	Cause: Order size is below the minimum required for the market. Solution: Increase order size to meet the minimum lot size requirement.
Price Band	`price band`, `outside range`	Cause: Order price is outside the allowed price band range. Solution: Adjust price to be within the market’s price band limits.
Position Order Conflict	`POSITION_STATE_ORDER_PRICE`	Cause: Market close order plus pending limit orders exceeds current position size. Solution: Cancel some limit orders or reduce the close amount.
Atomic Constraints	`ATOMICS_DUPLICATE_CANCEL`	Cause: The same order was targeted by multiple cancel sub-actions within a single atomic batch. Solution: Remove duplicate cancel entries from the atomic actions array.
Risk (Liquidation)	`RISK_NOT_ENOUGH`	Cause: The target account is not under sufficient risk for the requested liquidation action. Solution: This is a liquidation-only error. The account does not meet the risk threshold for liquidation.
Transfer	`SOURCE_AND_TARGET_SHOULD_NOT_BE_EQUAL`	Cause: Transfer source and destination accounts are the same. Solution: Specify different account IDs for the source and destination.
Trigger Execution	`NO_POSITION`, `PLANNING_FAILED`, `BANKRUPTCY`, `RISK_CHECK_FAILED`, `REDUCE_ONLY_CHECK_FAILED`	Cause: A trigger order (TP/SL) failed to execute. Common reasons: no open position exists, the execution plan could not be built, the account is bankrupt, or the resulting state would violate risk/reduce-only constraints. Solution: Check that the position still exists and the account is healthy before relying on trigger execution.
Nord Initialization	`Invalid public key input`	Cause: Incorrect app ID when initializing Nord. Solution: Verify the application ID used during initialization.