Recovery patterns

Concrete fixes for the most common integration failures.

Wrong RPC for the transaction

Account & funds transactions (deposit, deposit-direct, init-*, delegate-basket, withdraw, custody-settlement, withdrawal-settle) go to your Solana RPC; trading transactions go to the v2 RPC. Submitting one to the wrong endpoint fails. See Signing & submitting.

"Basket not delegated" / trade rejected

A trade was submitted before the basket was delegated. Ensure delegate-basket has confirmed and the basket is currently delegated. → Funds lifecycle

Insufficient collateral despite a deposit

deposit / deposit-direct submit to your Solana RPC; their funds must be confirmed (and credited to the deposit ledger) before they're usable. Confirm the deposit first.

withdraw returns custodySettlementRequired: true

The trade vault can't cover the amount yet. POST custody-settlement ({ owner, tokenSymbol }) first, wait for it to land, then retry withdraw. → Withdraw funds

Withdrawal funds didn't arrive

withdraw releases funds asynchronously and closes the escrow receipt once they land. If the receipt hasn't closed after a reasonable wait, call withdrawal-settle ({ owner, tokenMint }) to resume it.

feePayer rejected on a withdrawal

withdraw and request-withdrawal require a feePayer that differs from owner — the delegation program rejects owner == feePayer. Use a separate client-owned account (funded by the owner, optionally via feePayerTopUpLamports) and co-sign with both keys.

SOL withdrawn but balance unchanged

Withdrawn SOL arrives as WSOL in your ATA (isNativeSol: true). Unwrap the WSOL account back to native SOL after the withdrawal completes.

"Blockhash not found" / "expired"

Built transactions embed a blockhash that expires in ~45s. Rebuild via the endpoint and submit immediately. 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 /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 and the committed state appearing.

Compute error in a 200 body

A quote endpoint returned { "err": "…" } — the request was well-formed but the engine couldn't price it. Fix the inputs (symbols, side, amounts) and rebuild.