Error codes
Every rejection has error.code, retryable and hint; when a fix is
certain also suggested_args, and when only the person can act, human_action_url. Codes to
retry later also carry retry_after (seconds); over REST they come with HTTP 429 or 503 and a
Retry-After header. TradeHub never answers with a bare 500.
| Code | Who | Meaning | What to do |
|---|---|---|---|
INVALID_PARAMS | change the call | An argument is missing, of the wrong type or out of range; error.rule names it. | Fix that argument as error.hint says and call again. |
PREVIEW_EXPIRED | change the call | The preview is older than 30 seconds, was already used, or belongs to another agent. | Preview again and execute within 30 seconds. |
PRICE_MOVED | change the call | The mark moved more than the allowed drift between preview and execution. | Preview again at the new price. |
RATE_LIMITED | retry later | Too many calls: the per-agent rate, the daily account quota or the anonymous per-IP limit. | Wait retry_after seconds. Closing, cancelling and the emergency stop are never limited. |
CLIENT_ORDER_ID_REQUIRED | change the call | execute_previewed_order needs your own client_order_id. | Pass a unique client_order_id; reuse it only to retry the same order. |
TOO_MANY_PENDING | retry later | This agent already has the maximum number of orders waiting for approval. | Wait for the person to decide; do not resubmit. |
REQUEST_NOT_FOUND | do not retry | No such order request for this agent. | Check the request_id. |
REQUEST_NOT_PENDING | do not retry | The request was already decided, executed or expired. | Read it with get_order_request_status. |
APPROVAL_EXPIRED | change the call | Nobody approved the order in time. | Preview and execute again if still wanted. |
ORDER_NOT_FOUND | do not retry | No such resting order that this caller may touch. | List orders with get_my_open_orders. |
NO_POSITION | do not retry | No open position in that symbol on that venue that this caller may close. | List positions with get_my_open_positions. |
REJECTED | do not retry | Rejected for an unspecified reason. | Read error.hint; ask the person if unclear. |
AUTH_REQUIRED | change the call | This tool or venue needs an account; without one only public market data is available. | Connect to /mcp with OAuth or use an API key; on the sandbox, POST /v1/trial gives a 24-hour key. |
INSUFFICIENT_SCOPE | the person must act | The API key or the app's sign-in lacks a scope this tool needs; error.required lists them. | Ask the person for a key or sign-in with those scopes. |
SCOPE_INSUFFICIENT | the person must act | This agent's trading permissions do not allow this kind of action (e.g. it is read-only). | Ask the person to change the agent's permissions on the Web. |
KILL_NOT_ALLOWED | do not retry | Only first-party clients and the user's own keys may use the emergency stop. | Ask the person to stop trading on the Web or in Telegram. |
APPROVAL_NOT_ALLOWED | do not retry | Agents can never approve orders; only a person on the Web or Telegram can. | Tell the person an order is waiting. |
AGENT_PAUSED | the person must act | The agent is paused (five rejections in a row, or a stop). | Ask the person to resume it on the Web; check why orders were rejected first. |
AGENT_REVOKED | do not retry | The person revoked this agent. | Stop trading. |
MANDATE_NOT_FOUND | the person must act | This agent has no trading permissions. | Ask the person to create one on the Web. |
MANDATE_EXPIRED | the person must act | The agent's trading permissions have expired. | Ask the person to renew it on the Web. |
MANDATE_SYMBOL | the person must act | This agent's permissions do not include this symbol. | Use an allowed symbol or ask the person. |
MANDATE_ACTION | the person must act | This agent's permissions do not allow this action (e.g. shorts). | Ask the person. |
MANDATE_VENUE | the person must act | This agent's permissions do not include this venue. | Use an allowed venue or ask the person. |
MANDATE_LEVERAGE | change the call | Leverage is above this agent's permitted limit. | Use error.suggested_args (the limit). |
MANDATE_RISK | change the call | Loss at the stop is above this agent's permitted share of equity. | Use error.suggested_args (a smaller size_base) or move the stop closer. |
MANDATE_NOTIONAL_EXCEEDED | change the call | The order's value is above this agent's permitted USD limit. | Use error.suggested_args (a smaller size_base). |
MANDATE_POSITIONS | change the call | This agent's permitted number of open positions is reached. | Close a position first. |
MANDATE_DAILY_LOSS | the person must act | This agent's daily loss budget is used up. | Stop until tomorrow (UTC). |
MANDATE_DAILY_ORDERS | the person must act | This agent's daily number of orders is used up. | Stop until tomorrow (UTC). |
RISK_ACCOUNT_STATE | retry later | The account's state could not be read for the risk checks. | Retry shortly. |
RISK_POSITION | change the call | Loss at the stop is above the person's per-trade share of equity. | Use error.suggested_args (a smaller size_base) or move the stop closer. |
RISK_DAILY | the person must act | The daily loss limit is reached. | Stop trading until it resets. |
RISK_WEEKLY | the person must act | The weekly loss limit is reached. | Stop trading until it resets. |
RISK_MONTHLY | the person must act | The monthly loss limit is reached. | Stop trading until it resets. |
RISK_DRAWDOWN | the person must act | The drawdown from peak equity is at its limit. | Stop trading; tell the person. |
RISK_CONCURRENT | change the call | The maximum number of open positions is reached. | Close a position first. |
RISK_LEVERAGE | change the call | Leverage is above the person's limit. | Use error.suggested_args (the limit). |
RISK_SYMBOL | the person must act | The person's limits do not allow this symbol. | Use another symbol or ask. |
RISK_MARGIN | change the call | Not enough free margin for this order. | Reduce size_base or leverage. |
STOP_LOSS_REQUIRED | change the call | Every opening order needs a stop-loss. | Add stop_loss. |
STOP_LOSS_NOT_TIGHTER | change the call | A held position's stop can only move toward the price (and must stay on the loss side of the mark). | Pick a price between the current stop and the mark; to exit, close the position. |
STOP_LOSS_WRONG_SIDE | change the call | The stop is on the wrong side of the entry. | Put it below entry for a buy, above for a sell. |
PLATFORM_SYMBOL | do not retry | TradeHub does not trade this symbol. | Use a listed symbol (see tradehub.json). |
PLATFORM_LEVERAGE | change the call | Leverage is above TradeHub's cap. | Use error.suggested_args (the cap). |
PLATFORM_RISK | change the call | Loss at the stop is above TradeHub's per-trade cap. | Use error.suggested_args (a smaller size_base). |
PLATFORM_PRICE_BAND | change the call | A limit price crosses the mark by more than the price band, or a market order is larger than the book inside the band. | Use error.suggested_args (a price inside the band, or a smaller size_base). |
PLATFORM_SIZE | change the call | The size rounds down to zero at the venue's step. | Use a larger size_base. |
PLATFORM_VENUE | the person must act | The venue is not connected for this user. | Use a connected venue, or ask the person to connect it on the Web. |
PLATFORM_HALTED | retry later | TradeHub's operators stopped new positions for everyone; closing still works. | Do not open positions until it is lifted. |
TRADING_HALTED | the person must act | Trading is stopped for this account (emergency stop); closing still works. | Only the person can resume, on the Web. |
VENUE_MARGIN | change the call | Not enough free margin on this venue. | Use error.suggested_args or lower leverage. |
VENUE_UNAVAILABLE | retry later | The exchange did not answer or is failing. | Retry later; see get_venue_health. |
VENUE_OUTCOME_UNKNOWN | change the call | The exchange call started but TradeHub could not confirm how it ended. | Check get_order_request_status or get_my_open_positions before acting; repeating execute_previewed_order with the same client_order_id never places a second order. |
INTERNAL_ERROR | retry later | TradeHub itself failed unexpectedly; nothing was decided about your call. | Retry after retry_after seconds; an order retried with the same client_order_id is never placed twice. If it keeps failing, stop and give the person error.trace_id. |
ORDER_VOIDED | do not retry | The order was cancelled before it reached the exchange because the agent, its permissions or the account changed (paused, revoked, stopped). | Check get_my_trading_permissions before trying again. |
UNSUPPORTED | do not retry | This exchange does not support that operation. | Use another venue or tool. |
NOT_FILLED | change the call | A market order found nothing to fill within the price band when it reached the exchange; nothing was opened. | Check the book (get_order_book), then preview again. |
TOO_MANY_TRIGGERS | change the call | This agent already has 5 trigger entries armed or waiting for approval. | Cancel one it no longer needs with cancel_open_order(order_id=req_…), then place this one. |
TAKE_PROFIT_SIDE | change the call | A take-profit must be on the profit side: above the entry (or the mark, for one on a held position) for a long, below for a short. | Pick a price beyond error.limit on the profit side and call again. |
VENUE_REJECTED | do not retry | The exchange rejected the order. | Read error.hint; do not retry unchanged. |
STOP_LOSS_FAILED | the person must act | The order filled but the stop could not be placed; TradeHub closed the position. | Tell the person; check get_my_open_positions. |
SANDBOX_MARGIN | change the call | Not enough play money in the sandbox. | Reduce size_base, or reset the sandbox on the Web. |
REDUCE_ONLY_REJECTED | do not retry | The exchange refused the reduce-only close. | Check the position and retry. |
LEVERAGE_NOT_SET | retry later | The exchange did not accept the leverage setting. | Retry, or use lower leverage. |
STOP_UNCONFIRMED | the person must act | The exchange did not confirm the stop order. | Check get_my_open_orders. |
PRICE_REQUIRED | change the call | A limit order needs a price. | Add price, or use order_type market. |
HYPERLIQUID_REJECTED | do not retry | Hyperliquid rejected the order. | Read error.hint. |
HYPERLIQUID_ERROR | retry later | Hyperliquid returned an error. | Retry later. |
PAPER_LEVERAGE | change the call | Leverage above the test venue's maximum. | Lower leverage. |
PAPER_LOT_SIZE | change the call | Size not on the test venue's step. | Round size_base. |
PAPER_REDUCE_ONLY | do not retry | The test venue refused a reduce-only order. | Check the position. |
PAPER_REJECTED | do not retry | The test venue rejected the order. | Read error.hint. |
ACCOUNT_REFUSED | the person must act | The exchange account's credentials were refused when connecting it. | Check the key or API wallet and connect it again on the Web. |
KEY_CAN_WITHDRAW | the person must act | The exchange key can withdraw funds; TradeHub refuses such keys. | Create a key without withdrawal rights. |
HYPERLIQUID_KEY_REJECTED | the person must act | Hyperliquid does not recognise this API wallet for the account. | Approve the API wallet on Hyperliquid first. |
BYBIT_ACCOUNT_MODE | the person must act | Bybit needs a unified account in one-way mode. | Change it on Bybit. |
OKX_ACCOUNT_MODE | the person must act | OKX account mode not supported. | Change it on OKX. |
OKX_POSITION_MODE | the person must act | OKX needs one-way (net) position mode. | Change it on OKX. |