Perp Order Reason Codes
When the order form says an order "would be rejected", it is quoting a reason code. The same code comes back from the live check before you sign (the preview) and from the real submit, so what the form shows is what the server would do.
How the form uses them:
- Blocking codes turn the submit button into the reason (for example
Not enough margin) until you change the order. - Refresh codes (
stale_position_snapshot,venue_risk_unavailable) are re-checked automatically and never block the button. - Retry-and-block codes (
price_unavailable,account_health_unavailable) are also re-checked automatically, but block the button until the check passes. - A failed preview never blocks you. If the preview cannot be reached, the form shows no numbers and you can still submit. The real check still runs on submit.
invalid_order,engine_rejectedand any unknown code block and show the server's message as written, since it names the field or rule that failed.
API users get the same value in reasonCode on POST /v1/tee-perp/preview and on order, batch and leverage submit responses. The human-readable text (reason on the preview, message on submit responses) is diagnostic; branch on the code.
Margin and position
| Code | What it means | What to do |
|---|---|---|
insufficient_margin | After this order (and every open perp order) fills, your account would not cover its requirement. The requirement is the worse of Hypercall portfolio margin and Hyperliquid margin. | Use the card the form shows: Use max (largest size that passes), Raise to N× (smallest leverage that passes), or Deposit the shortfall. Cancelling resting orders also frees margin. |
reduce_only_exceeds_position | A reduce-only order would grow or flip your position instead of shrinking it. | Set the size at or below your open position (the form offers Use position), or turn off Reduce only. |
mode_change_with_position | You tried to switch cross and isolated on a market where you hold a position. Hyperliquid does not allow it either. | Keep the current mode, or close the position and switch. |
leverage_requires_flat_account | A leverage change was refused because the account has open perp positions or pending perp orders. This only happens where Hypercall does not charge Hyperliquid liquidation risk in margin; production charges it, so production does not return this code. | Close positions and cancel perp orders, then change leverage. |
liquidation_pending | The account is in pre-liquidation with a full liquidation about to start. Hypercall refuses new perp orders on the account. | Wait for the liquidation to resolve. See Liquidation. |
Account setup
| Code | What it means | What to do |
|---|---|---|
account_not_pm | Perp orders need a portfolio margin account. | Turn on portfolio margin from your account page, then retry. |
unified_mode_required | Orders that add risk need Hyperliquid unified account mode on the trading account. | Click Enable unified mode in the form. |
builder_not_approved | Hyperliquid refused the order because the account has not approved Hypercall's builder address. This comes back from Hyperliquid at submit, not from the preview, and API users see it in the submit response's errorCode, not reasonCode. | Click Enable trading once. See Perps on Hypercall. |
account_health_unavailable | Hypercall cannot read the account's margin health right now, so it refuses anything that adds risk. | The form re-checks automatically. To cut risk in the meantime, send the order with Reduce only on. |
Market and data
| Code | What it means | What to do |
|---|---|---|
market_not_supported | The market is not one Hypercall can risk. It needs a price feed, a margin scenario grid and a USDC-margined Hyperliquid schedule for your account. | Pick a supported market. |
trading_halted | Trading is paused, either everywhere or for this market. | Wait. The form keeps the button disabled until trading resumes. |
price_unavailable | The price Hypercall uses to value the market is missing or stale. | The form re-checks automatically. Hypercall does not guess a price, so it refuses until a fresh one arrives. |
stale_position_snapshot | Your latest Hyperliquid position or equity reading is missing or too old. | Nothing. The form re-checks once on its own. If it persists, refresh. |
venue_risk_unavailable | The Hyperliquid risk reading (leverage, liquidation prices, collateral per position) is missing or does not match your latest position reading. | Nothing. The form re-checks once on its own. |
Order terms
| Code | What it means | What to do |
|---|---|---|
invalid_order | The order terms are invalid: price or size precision, a malformed TP/SL bracket, or a bad client order id. | Fix the price tick or size step and resubmit. |
action_not_supported | The signing enclave's policy does not allow this kind of action. If it happens on an order type the form offers, the form marks that type as not enabled. | Use a supported order type. |
engine_rejected | Any other refusal. The reason text carries the exact cause. | Read the message. If it is unclear, contact support with the text. |