Trading Errors

These are the most common user-actionable errors clients hit when placing or modifying orders, or when setting up an agent wallet for trading. Each entry lists the slug, status code, when it surfaces, and how to resolve it. Match on the slug (the final path segment of type), not the title or status alone — see Errors for the contract.

agent_not_approved (400)

When: Calling a trading endpoint without an approved agent for the active DEX/account. Resolve: Call POST /v1/agent/approve and retry. If approval stays pending, see agent_approval_pending.

agent_approval_pending (409)

When: Agent approval has been submitted but not yet finalized on-chain. Resolve: Wait briefly and retry. Typically resolves in under 30 seconds.

oi_cap_reached (403)

When: An opening order would push asset open interest past the per-asset HIP-3 cap. Resolve: Reduce size, wait for OI to free up, or contact ops to raise the cap.

dex_oi_cap_reached (403)

When: An opening order would push DEX-wide open interest past the aggregate cap. Resolve: Same as oi_cap_reached but at the DEX aggregate level — wait for OI to free up across the DEX or contact ops.

close_only_mode (403)

When: The asset is in close-only mode (settlement window or feed degradation). Opening orders are rejected; closing orders still work. Resolve: Wait for the next bucket boundary. Check /v1/bucket for state.

reduce-only-required (400)

When: An order is missing the reduceOnly flag while a position is in close-only mode or the asset enforces reduce-only. Resolve: Resubmit the order with reduceOnly: true.

price-outside-oracle-band (422)

When: The submitted limit price is outside the per-asset clamp around the oracle mark (HIP-3 enforces a ±1% band per oracle update). Resolve: Resubmit closer to the current mark. Consult /v1/markets for the band.

market-halted (400)

When: The asset is halted (settlement boundary, emergency, or operator halt). All new orders are rejected. Resolve: Wait for the asset to resume. Subscribe to activeAssetCtx for status changes.

unknown-asset (400)

When: The asset code is not registered on this DEX. Resolve: Check /v1/markets for valid asset codes.

invalid-leverage (400)

When: The leverage value is not an integer in 1..=100. The API enforces a flat 1..=100 clamp regardless of the asset. Resolve: Resubmit with an integer leverage in 1..=100. (Margin-tier-aware sizing is supplemental — consult /v1/markets if you also need tier metadata, but the bound that produces this error is the flat 1..=100 clamp.)

unsupported-tif (400)

When: The time-in-force value is not in {ALO, IOC, GTC}. Resolve: Use one of the supported TIFs.

invalid-side (400)

When: The order side is not buy or sell (matching is case-insensitive). Resolve: Submit side: "buy" or side: "sell".

no-safe-liquidity (422)

When: The order would consume liquidity beyond the safety bounds (e.g. spot-price aggressor protection or stale-book guard). Resolve: Reduce size or use a more conservative limit price.