Error Code
Business errors on Stock Option Trading endpoints return HTTP 400 (-1003 returns 429, -1004
returns 503, and -1000 may return 500) with the standard SAPI error envelope:
Code
codeis an integer and can be: a standard SAPI code (negative); an option business code (497xxx); a Stocks Trading code (486xxx, returned by Cancel Option Order, Cancel All Option Orders and Option Order Detail, see Stocks Trading Error Code); or a compliance code (when Place Option Order or Submit Option Exercise fails a compliance check, the compliance code and message are returned as-is). Handle errors bycode.msgis in English.{0}in a message is replaced with the actual value (e.g. a number of minutes or a strike price).- Several codes can share the same
msg. For example,The system is temporarily unavailable. Please try again later.is used by497001/497301/497305/497417/497430, andThis option contract has expired.is used by497425(orders) and497511(exercise).msgis meant for end-user display; handle errors bycode, not by matchingmsg. - The
errorCodefield of Option Exercise Detail is an option business code (497xxx), returned as a string.
SAPI General Codes
| Code | Message | When |
|---|---|---|
-1102 | Mandatory parameter 'quantity' was not sent, was empty/null, or malformed. | A parameter is missing or malformed; the quoted name is the parameter. E.g. non-integer quantity, timeInForce other than DAY, invalid side / positionIntent, expirationDate not in YYYY-MM-DD, unknown symbol or contract info temporarily unavailable (Place Option Order, Option Exchange Info; retry later for the latter), empty symbol on Option Exchange Info, unknown eventId |
-1102 | Param 'orderId' or 'clientOrderId' must be sent, but both were empty/null! | Option Order Detail without orderId and clientOrderId |
-1102 | Param 'tranId' or 'clientOrderId' must be sent, but both were empty/null! | Option Exercise Detail without tranId and clientOrderId |
-1121 | Invalid symbol. | Option Expirations: the underlying does not exist or has no listed options |
-2013 | Order does not exist. | Option Order Detail: the order is a stock order |
486218 | Order not found | Option Order Detail: the order does not exist, or orderId and clientOrderId do not belong to the same order |
-26004 | Symbol [NVDAX] is not exists | Option Order History, Option Trade History: underlyingSymbol is not a listed US stock (the bracket shows the value passed in) |
-3026 | Required request parameter 'symbol' for method parameter type String is not present | Option Exchange Info without the symbol parameter (an empty value returns -1102) |
-31002 | (parameter validation message, in English) | Invalid parameter combination on Place Option Order: positionIntent omitted and cannot be derived from the current position, or positionIntent does not match side |
-1003 | Too many requests; current request has limited. | HTTP 429, per-UID rate limit exceeded (see Rate Limits) |
-99020 | Not a valid whitelisted user id. | The caller's account does not have Stock Option Trading API access yet |
-1004 | Server is busy, please wait and try again | HTTP 503. Fee rates are temporarily unavailable at placement, or the contract is missing pricing parameters such as multiplier or strike. Retry later |
-1000 | An unknown error occurred while processing the request. | Internal server error or a dependency is temporarily unavailable (HTTP 500). Retry later; for orders, retry with the same clientOrderId |
-9000 | Passes through the downstream message | The downstream returned a code without a registered message. Not expected in normal operation |
Option Business Codes
General
| Code | Message | When | Endpoints |
|---|---|---|---|
497001 | The system is temporarily unavailable. Please try again later. | System busy or downstream timeout. The order / exercise may still be processing; handle it the same way as 497301 | Place Option Order, Submit Option Exercise |
497301 | The system is temporarily unavailable. Please try again later. | The broker call failed or returned an unknown error. For orders, the order may still be processing; this does not mean it failed. Do not retry with a new clientOrderId. Retry with the same clientOrderId (idempotent — if the original order was accepted or is processing, it is returned directly), or query Option Order Detail by clientOrderId for the final status. The same applies to Submit Option Exercise (query Option Exercise Detail) | Place Option Order, Submit Option Exercise |
497417 | The system is temporarily unavailable. Please try again later. | Server-side fee configuration error | Place Option Order |
497430 | The system is temporarily unavailable. Please try again later. | The user's trading restriction status is temporarily unavailable; affects opening orders only (BUY_TO_OPEN / SELL_TO_OPEN) | Place Option Order |
Account and Eligibility
| Code | Message | When | Endpoints |
|---|---|---|---|
497203 | Please open an options trading account before placing an order. | Options not enabled for the account. Enable it in the App first; closing orders are rejected too | Place Option Order, Submit Option Exercise |
497202 | Your account is not authorized for trading. | The brokerage trading account is unavailable (not activated or restricted from trading) | Place Option Order, Submit Option Exercise |
497424 | Your account type does not support options trading. | The account type does not support options | Place Option Order |
497428 | Your Equity Options trading is currently in Reduce-Only mode. Opening or increasing positions is not allowed — you can only close existing positions. Please contact support if you have questions. | The account is reduce-only: opening (BUY_TO_OPEN / SELL_TO_OPEN) is rejected, closing is allowed | Place Option Order |
497408 | You have reached your daily trading limit. | The platform's daily available trading quota is insufficient (a platform-level quota, not a per-account limit); applies only to buy to open, buy to close and cash-secured put opening orders | Place Option Order |
Contract and Trading Status
| Code | Message | When | Endpoints |
|---|---|---|---|
497302 | Option contract not found. Please check the symbol. | The contract does not exist, or its metadata is incomplete or temporarily unavailable. An unknown symbol on Place Option Order is rejected earlier with -1102, so this code is mainly seen on exercise | Place Option Order, Submit Option Exercise |
497305 | The system is temporarily unavailable. Please try again later. | Buying to close (BUY_TO_CLOSE) a covered-call short on a corporate-action-adjusted contract whose deliverable data is not ready yet, so the collateral shares to return cannot be calculated. Recovers automatically once the data is complete; retry later | Place Option Order |
497303 | This option is currently unavailable for trading. | The broker considers the contract not tradable at the moment | Place Option Order |
497418 | Options trading is not available for this underlying stock. | Options trading is not enabled for the underlying, or the underlying's trading configuration is temporarily unavailable (retry later) | Place Option Order |
497426 | This option contract is currently unavailable for trading. | The contract is delisted or suspended; opening and closing are both rejected. Corresponds to status = NONE | Place Option Order |
497425 | This option contract has expired. | Past the close on the expiration day; opening and closing are both rejected | Place Option Order |
497427 | Only closing orders are allowed for this option contract. | The contract is close-only; opening is rejected. Corresponds to status = CLOSE_ONLY | Place Option Order |
497423 | Only closing orders are allowed within {0} minutes before market close on the expiration date. | Within the last period before the close on the expiration day ({0} is the number of minutes, 45 by default), only closing is allowed. status does not reflect this window, see status | Place Option Order |
Order Parameters
| Code | Message | When | Endpoints |
|---|---|---|---|
497104 | This quote asset is not supported. | quoteAsset is not USDC | Place Option Order, Submit Option Exercise |
497419 | Order quantity is below the minimum. | Quantity below minQty | Place Option Order |
497420 | Order quantity exceeds the maximum. | Quantity above maxQty | Place Option Order |
497421 | Please enter a whole number of contracts. | Quantity is not a multiple of stepSize (a non-integer quantity is rejected earlier with -1102) | Place Option Order |
497422 | Please enter a limit price in a valid increment. | Limit price is not a multiple of tickSize | Place Option Order |
497415 | Minimum order value is $1. | Order notional below minNotional. The amount in the message is the default; the actual minimum is minNotional in Option Exchange Info | Place Option Order |
497414 | Order value exceeds the maximum of $500,000. | Order notional above maxNotional. The amount in the message is the default; the actual maximum is maxNotional in Option Exchange Info | Place Option Order |
497438 | The limit price for a put sell order cannot exceed the strike price ({0}). | The limit price of a put sell order (opening or closing) is above the strike; {0} is the strike | Place Option Order |
497401 | Failed to submit the order. Please try again. | Duplicate clientOrderId, and the original order with that ID has failed. If the original order succeeded or is still processing, the original order is returned instead | Place Option Order, Submit Option Exercise |
497416 | Payment amount does not match the order total. Please review your order and try again. | Fees changed at the moment of placement, so the payment amount no longer matches the order total. Retry directly | Place Option Order |
Positions and Funds
| Code | Message | When | Endpoints |
|---|---|---|---|
497404 | Insufficient buying power. Please reduce the order size or add funds and try again. | Insufficient balance in the payment wallet: when buying, not enough to pay the premium plus fees; when selling to open, not enough to lock the collateral (shares for a covered call, cash for a cash-secured put) | Place Option Order |
497407 | Insufficient collateral to place this order. | Buying to close (BUY_TO_CLOSE): the collateral locked for the short position is insufficient and cannot be transferred | Place Option Order |
497405 | Insufficient option contracts available. Please check your position. | Closing quantity exceeds the available position (contracts reserved by open orders are not available) | Place Option Order |
497431 | You hold a short position in this option. Please close it before opening a long position. | Buying to open while holding a short position in the contract. Close the short first | Place Option Order |
497432 | You hold a long position in this option. Please close it before opening a short position. | Selling to open while holding a long position in the contract. Close the long first | Place Option Order |
497435 | You have pending sell-to-open orders for this option. Please cancel all of them before opening a long position. | Buying to open while sell-to-open orders are open on the contract. Cancel them first | Place Option Order |
497436 | You have pending buy-to-open orders for this option. Please cancel all of them before opening a short position. | Selling to open while buy-to-open orders are open on the contract. Cancel them first | Place Option Order |
497434 | Selling to open is not supported for this adjusted option. You can still close existing positions. | Selling to open a call on a corporate-action-adjusted contract (or one whose deliverables are pending confirmation). Closing is not affected | Place Option Order |
Exercise
| Code | Message | When | Endpoints |
|---|---|---|---|
497508 | No exercisable long position found for this option. | No exercisable long position in the contract | Submit Option Exercise |
497504 | Exercise quantity exceeds the number of contracts available to exercise. Please reduce the quantity and try again. | Exercise quantity exceeds availableQty | Submit Option Exercise |
497505 | Insufficient funds to exercise this call option. Please add funds or reduce the exercise quantity and try again. | Insufficient cash to exercise a call (strike × contracts × multiplier is required); also returned when an adjusted put contract's cash deliverable is insufficient | Submit Option Exercise |
497506 | Insufficient underlying shares to exercise this put option. Please check your holdings. | Insufficient underlying shares to exercise a put | Submit Option Exercise |
497511 | This option contract has expired. | The contract has expired | Submit Option Exercise |
497507 | Exercise requests are not available at this time. Please try again later. | Exercise is not accepted between the daily close and 00:00 ET the next day | Submit Option Exercise |
497515 | Exercise requests are not accepted near market close on the expiration date. | From 30 minutes before the close on the expiration day (or the last trading day before it if the expiration day is not a trading day): normally 15:30 ET, adjusted on early-close days and for underlyings with optionsLateClose | Submit Option Exercise |
497513 | This non-standard option contract cannot be exercised online. Please contact support. | Puts on non-standard contracts (deliverables missing or unrecognized) cannot be exercised online | Submit Option Exercise |
497406 | No position found for this option. | The broker finds no exercisable position in the contract | Submit Option Exercise |
497501 | Unable to submit the exercise request. Please try again later. | The exercise submission failed (e.g. funds could not be locked) | Submit Option Exercise |
497402 | Order not found. | No exercise record found by tranId / clientOrderId, or the record does not belong to the caller | Option Exercise Detail |
Was this page helpful?
Last modified on