Error Reference

All errors follow this shape:

{
  "statusCode": 400,
  "code": "POSITION_INSUFFICIENT_BALANCE",
  "message": "Insufficient balance — you need enough collateral token + protocol fee (~1%), AND ~0.01 SOL for transaction fees and account rent.",
  "detail": null,
  "path": "/api/v1/positions/open-by-token",
  "timestamp": "2026-03-15T12:00:00.000Z"
}

Match on the code field — it is a stable string. The message is human-readable and may change.

Authentication Errors

Code	HTTP	Message	Action
`AUTH_MISSING_KEY`	401	Missing x-api-key header.	Add the `x-api-key` header to your request.
`AUTH_INVALID_KEY`	401	Invalid API key.	Check the key is correct and not malformed.
`AUTH_REVOKED_KEY`	401	API key has been revoked.	Request a new key from [email protected].
`AUTH_MISSING_ADMIN_TOKEN`	401	Missing admin authorization token.	Admin endpoints only — not applicable to partner integrations.
`AUTH_INVALID_ADMIN_TOKEN`	401	Invalid or expired admin token.	Admin endpoints only.
`AUTH_INVALID_PASSWORD`	401	Invalid password.	Internal — not returned to partners.
`AUTH_MISSING_WALLET_SIGNATURE`	401	Missing wallet signature headers.	Include `x-wallet-address`, `x-wallet-signature`, `x-wallet-message` for order endpoints.
`AUTH_INVALID_WALLET_SIGNATURE`	401	Invalid wallet signature.	Verify signature is a valid Ed25519 signature of the message.
`AUTH_WALLET_SIGNATURE_EXPIRED`	401	Wallet signature has expired (max 5 minutes).	Regenerate the signature with a current timestamp.
`AUTH_WALLET_MISMATCH`	403	Wallet address in body does not match signed wallet.	The `userPublicKey` in the request body must match `x-wallet-address`.
`AUTH_MISSING_LP_KEY`	401	Missing x-lp-api-key header.	LP endpoints only — use `x-lp-api-key` not `x-api-key`.
`AUTH_INVALID_LP_KEY`	401	Invalid LP API key.	Check the LP API key.
`AUTH_REVOKED_LP_KEY`	401	LP API key has been revoked.	Generate a new LP API key from the Lenders Portal.

Rate Limiting

Code	HTTP	Message	Action
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded. Please wait before retrying.	Back off exponentially. Start with 1s, double on each retry.

Offer Errors

Code	HTTP	Message	Action
`OFFER_NOT_FOUND`	404	Offer not found.	The `offerPublicKey` does not exist or is inactive. Use `open-by-token` instead.
`NO_OFFER_FOR_TOKEN`	404	No active offer found for the requested token and side.	No liquidity available for this token/side combination. Check `GET /api/v1/offers` for supported tokens.

Token Errors

Code	HTTP	Message	Action
`TOKEN_NOT_FOUND`	404	Token not found.	The token mint is not indexed. Check `GET /api/v1/tokens` for supported tokens.

Position Errors

Code	HTTP	Message	Action
`POSITION_NOT_FOUND`	404	Position not found.	The position address doesn't exist in the database.
`POSITION_NOT_FOUND_ONCHAIN`	404	Position account not found on chain.	The position was already closed on-chain.
`POSITION_OFFER_NOT_FOUND_ONCHAIN`	404	Offer account not found on chain.	The liquidity pool was removed on-chain.
`POSITION_NOT_OWNER`	403	Position does not belong to the specified wallet.	Verify `userPublicKey` matches the position owner.
`POSITION_SIDE_MISMATCH`	400	Requested side does not match the pool direction.	The offer only supports one side. Use `open-by-token` for automatic matching.
`POSITION_INSUFFICIENT_BALANCE`	400	Insufficient balance.	User needs enough collateral + ~1% protocol fee + ~0.01 SOL for network fees and rent.
`POSITION_DUPLICATE`	409	Position already exists.	Duplicate request detected. Check if the previous transaction was already confirmed.
`POSITION_TX_TOO_LARGE`	400	Transaction too large.	Reduce slippage or retry. This can happen on complex swap routes.
`POSITION_SPLIT_FAILED`	500	Split did not return new position addresses.	Retry. If persistent, contact support.
`POSITION_MERGE_MISMATCH`	400	Both positions must belong to the same wallet.	Both positions must have the same `userPublicKey`.
`POSITION_MERGE_NOT_FOUND`	404	One or both positions not found on chain.	Verify both position addresses are valid and still open.
`POSITION_MISSING_PRICE`	400	No price data available for the requested token.	The oracle has no price for this token. Try again or use a different token.
`POSITION_NOT_AVAILABLE`	409	Position account is not yet available on-chain.	The open transaction was confirmed but the account hasn't propagated yet. Wait 2-3 seconds and retry.
`POSITION_TOO_SMALL`	422	Position size too small to cover protocol fee.	Increase the collateral amount. The minimum position size is approximately 0.01 SOL equivalent.
`POSITION_SWAP_ROUTE_FAILED`	400	Swap route failed — position may be too small for available liquidity pools.	Try a larger collateral amount. This indicates the swap pool has insufficient depth for the requested size.

Order Errors

Code	HTTP	Message	Action
`ORDER_NOT_FOUND`	404	Order not found.	The order ID doesn't exist.
`ORDER_NOT_OWNER`	403	Order does not belong to this API key.	Use the same API key that created the order.
`ORDER_INVALID_PRICE`	400	triggerPrice must be a positive number string.	Pass `triggerPrice` as a numeric string like `"155.50"`.
`ORDER_NOT_CANCELLABLE`	400	Only ACTIVE or FAILED orders can be cancelled.	Check the order status before attempting cancellation.
`ORDER_POSITION_NOT_OWNER`	403	Position does not belong to this API key.	The position was opened by a different API key.
`ORDER_WALLET_NOT_POSITION_OWNER`	403	Privy wallet does not belong to the position owner.	The delegated wallet must match the position owner.

Partner Errors

Code	HTTP	Message	Action
`PARTNER_KEY_NOT_FOUND`	403	Key not found or not owned by you.	The API key doesn't exist or belongs to a different partner.
`PARTNER_NOT_FOUND`	404	Partner not found.	Internal — the partner record for your API key was not found. Contact support.

Oracle Errors

Code	HTTP	Message	Action
`ORACLE_FEED_MISSING`	500	No oracle feed configured for the requested token.	The token exists but has no price feed. Contact support.

Swap / Jupiter Errors

Code	HTTP	Message	Action
`SWAP_QUOTE_FAILED`	422	Failed to get swap quote from Jupiter.	Retry. Jupiter may be temporarily unavailable.
`SWAP_BUILD_FAILED`	422	Failed to build swap transaction.	Retry.
`JUPITER_QUOTE_FAILED`	422	Jupiter returned no route for this swap.	Increase slippage or try a different token.
`JUPITER_SWAP_BUILD_FAILED`	422	Jupiter failed to build swap instructions.	Retry with higher slippage.
`TX_SIZE_EXCEEDED`	400	Transaction too large.	Reduce slippage (fewer alternative routes) or retry.
`SIMULATION_FAILED`	422	Transaction simulation failed.	The transaction would fail on-chain. Check parameters and retry.
`SLIPPAGE_EXCEEDED`	422	Price moved beyond slippage tolerance.	Increase `slippageBps` or retry immediately.

Bundle Errors

Code	HTTP	Message	Action
`BUNDLE_SUBMIT_FAILED`	422	Failed to submit Jito bundle.	Retry the partial-sell bundle submission.

Referral Errors

Code	HTTP	Message	Action
`REFERRAL_INVALID_CODE`	404	Invalid referral code.	Check the referral code is correct.
`REFERRAL_SELF_REFER`	400	Cannot refer yourself.	A wallet cannot be referred by its own referral code.
`REFERRAL_ALREADY_BOUND`	409	Already bound to a referrer.	A wallet can only be bound to one referrer.
`REFERRAL_WALLET_NOT_REGISTERED`	404	Wallet not registered in the referral program.	Register with `POST /api/v1/referral/register` first.

Staking Errors

Code	HTTP	Message	Action
`STAKING_VAULT_NOT_FOUND`	404	Staking vault not found.	Valid vault values are `SOL` and `USDC`.
`STAKING_POSITION_NOT_FOUND`	404	Staking position not found.	The staking position doesn't exist for this wallet.
`STAKING_POSITION_INACTIVE`	400	Staking position is not active.	The position has already been unstaked.

LP Errors

Code	HTTP	Message	Action
`LP_NOTIFICATION_NOT_FOUND`	404	Notification not found.	The notification ID doesn't exist.
`LP_API_KEY_NOT_FOUND`	404	LP API key not found.	Generate a key from the Lenders Portal.
`LP_VAULT_ALREADY_EXISTS`	409	A vault already exists for this operator + mint.	Each operator can only have one vault per quote token.
`LP_OFFER_ALREADY_EXISTS`	409	A trading pool already exists for this vault + collateral mint.	Each vault can only have one offer per collateral token.
`LP_VAULT_NOT_FOUND`	404	Vault not found on chain for this operator + mint.	Create a vault first with `POST /api/v1/lp/tx/create-vault`.

System Errors

Code	HTTP	Message	Action
`SERVICE_UNAVAILABLE`	503	Service is unhealthy.	Retry after a short delay. Check status at `GET /health`.
`VALIDATION_ERROR`	400	Request validation failed.	Check the `detail` field for which fields failed validation. The `detail` field contains the joined class-validator messages describing exactly which fields are invalid.
`INTERNAL_ERROR`	500	An unexpected error occurred.	Retry. If persistent, contact support with the request `timestamp` for debugging.

Retryable vs Non-Retryable Errors

Retryable (transient — exponential backoff recommended):

Code	Reason
`INTERNAL_ERROR`	Server-side transient failure
`SERVICE_UNAVAILABLE`	Server temporarily down
`SWAP_QUOTE_FAILED`	Jupiter temporarily unavailable
`SWAP_BUILD_FAILED`	Jupiter build failure
`BUNDLE_SUBMIT_FAILED`	Jito bundle submission failure
`POSITION_NOT_AVAILABLE`	Account propagation lag — retry after 2-3s
`SLIPPAGE_EXCEEDED`	Price moved — retry immediately
`SIMULATION_FAILED`	Transaction simulation failure — retry once

Non-retryable (fix the request, do not retry):

Code	Reason
`AUTH_INVALID_KEY`, `AUTH_REVOKED_KEY`	Bad credentials
`VALIDATION_ERROR`	Malformed request
`POSITION_NOT_FOUND`	Position does not exist
`POSITION_NOT_OWNER`	Wrong wallet
`POSITION_DUPLICATE`	Already submitted — check if confirmed
`POSITION_INSUFFICIENT_BALANCE`	Not enough funds
`POSITION_SIDE_MISMATCH`	Wrong pool direction
`NO_OFFER_FOR_TOKEN`	No liquidity for this token/side
`ORDER_NOT_CANCELLABLE`	Order already in terminal state