Order errors: placement and execution

When a user places a stock order, there are a variety of reasons for which it can go unplaced or rejected. We are now revamping how we inform users (on the order placement screen) and partners (via SDK, API, webhook) about what went wrong with the order.

Error sharing with the user ✨

Users will be explicitly informed of the reason for the order failure (SDK takes care of UI).

Below are the order status screens in case of order failure. These UI is handled by Gateway SDK itself -

1146 — securities transaction: order status screen

1496 — smallcase transaction: order status screen

Error sharing with the partner 🤝

The error details will be shared with you in the transaction responses which will be further consumable at your end. The error details are shared in order response via:

SDK response of trigger transaction method
API for stocks order details and smallcase order details
Stock order webhooks

In transaction response, each individual stock order has a status that identifies what happened to that particular stock in the order. errorCode and statusMessage fields for such individual stock can help with identifying what went wrong.

errorCode is a standardised code across all brokers that the gateway supports. It corresponds to a particular cause of failure. Possible codes are listed in the table below.
statusMessage is a message returned by the broker indicating any problems that occur while executing the order. The message is specific to the broker.

Error codes

errorCode	Description
adapterError	Gateway was unable to reach broker's systems
tradingSystemNotReady	brokers system is not accepting orders at the moment. Probably due to market being closed
checkHoldings	Users' broker account does not have sufficient holdings that are allowed to be sold.
marginsExceeded	Not enough funds to place the order or above the set limits for the account.
orderUnmatched	No buyers or sellers are available at the moment. This can happen due to liquidity issues or the stock hitting circuits.
circuitLimitExceeded	The price specified is not within circuit limits set by the exchange
checkFreezeQty	Entered quantity is greater than the allowed (freeze) quantity
qtyNotMultipleOfLot	Quantity does not meet lot requirements for this stock. More info
userNotLoggedIn	Could obtain authorization to place an order, the user may not be logged in or logged in session expired.
clientNotEnabled	The broker account doesn't have equity trading enabled
clientBlocked	Placing orders from this account is blocked.
exchgNotEnabled	The account is not allowed to place orders on the specified exchange
securityNotAllowed	The security is not allowed to be traded in this exchange
debtorNotAllowed	The user has a debit balance that needs to be cleared by adding more funds
sellNeedsAuth	Couldn't obtain authorization to sell holdings
ASMGSMList	Trading may be restricted in specified stocks as they are listed in the ASM or GSM category set by the exchange
stockTipsBlocked	Trading may be restricted in specified stocks by the exchange on reports of unsolicited messages
networkError	Couldn't fetch order status from the broker
kiteStockTipsBlocked	Trading may be restricted in specified stocks by the exchange on reports of unsolicited messages. Users can try placing the order again after enabling TOTP on their Zerodha account
kiteClientReactivationRequired	The account needs to be reactivated due to inactivity for over 12 months.
kiteClientNotEnabled	Your account is not setup for placing CNC orders.
kiteExchgNotEnabled	Your account is not setup for placing orders on the exchange.
kiteASMGSMList	Trading may be restricted in specified stocks as they are listed in ASM and GSM categories set by the exchange. Users can try placing the order again after enabling TOTP on their Zerodha account
kiteIllquidStocks	Trading may be restricted in specified stocks as they don't have sufficient liquidity in the market. Users can try placing the order again after enabling TOTP on their Zerodha account
exchangeMismatch	The sell order couldn't be executed on the specified exchange as the buy order was executed on a different exchange. Users can try again the next day.
intradayNotAllowed	Intraday/BTST is not allowed for the stock as they are Trade to Trade stocks. Users will be able to sell after the stocks are delivered to their account.
tradingSymbol	The trading symbol used is no longer valid.
omsMaintenance	Broker's order management system is under scheduled maintenance. Try placing the order after some time.
holdingsAuthorization	User needs to authorize sell orders on CDSL for the stock
dealerLocationmapping	Kotak client accounts need to be mapped to the dealer branch before placing orders
stockBlockedSymbolNotFound	The trading symbol used is no longer valid.
blockedNRI	User's account type does not support placing intraday orders
axisBlockednri	User's account type does not support placing intraday orders
kycPending	KYC verification has to be done for the demat account either because its newly opened or it has been inactive for >12 month
iciciKycPending	KYC verification has to be done for the demat account either because its newly opened or it has been inactive for >12 month
peakMargin	Due to peak margin rules, 100% of proceeds of a sell order is not available to invest on the same day. More funds are required to perform this transaction
otherError	Order failed due to an unclassified error. Please contact support for details if needed

Sample response

Securities transaction

{
  "notes": "your notes",
  "smallcaseAuthToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFsbGNhc2VBdXRoSWQiOiI2MjQ1NzkxNzI4MGU2YjA4NDFjMzBhYTEiLCJpYXQiOjE2NDg3MjAwMjMsImV4cCI6MTY0ODcyMzYyM30.-IjC7N9pEsdgsEzacGtrVSQ0DcvQoiWd9gD0w6RGC6c",
  "transactionId": "TRX_d45726a0d94941f4a816f0e7fcb37d71",
  "orderBatches": [
    {
      "filled": 1,
      "variety": "regular",
      "buyAmount": 1903.12,
      "sellAmount": 0,
      "orders": [
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "REJECTED",
          "quantity": 3,
          "tradingsymbol": "ADROITINFO",
          "transactionType": "BUY",
          "filledQuantity": 0,
          /* Error details key */
          "statusMessage": "Trading may be restricted in specified stocks as they are listed in ASM and GSM categories set by the exchange. Users can try placing the order again after enabling TOTP on their Zerodha account",
          "errorCode": "kiteASMGSMList"
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "COMPLETE",
          "quantity": 1,
          "tradingsymbol": "INFY",
          "transactionType": "BUY",
          "filledQuantity": 1,
          "averagePrice": 1903.12,
          "exchangeOrderId": "62457907f5a677a551800ae86245791ef5a677a551800b1f",
          /* Error details keys are also present with default values for success orders */
          "statusMessage": "NA",
          "errorCode": null
        }
      ],
      "unplaced": [],
      "batchId": "6245791c5b4a017dc8e2d943",
      "broker": "kite",
      "quantity": 2,
      "status": "MARKEDCOMPLETE",
      "completedDate": "2022-03-31T09:49:21.434Z",
      "transactionId": "TRX_d45726a0d94941f4a816f0e7fcb37d71"
    }
  ],
  "broker": "kite"
}

(single stock, basket orders)

smallcase transaction

{
  "notes": "your notes",
  "smallcaseAuthToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzbWFsbGNhc2VBdXRoSWQiOiI2MjQzZjZjZWJhMGZhYTdlOTg3YWM5ZjEiLCJpYXQiOjE2NDg2MjY3ODIsImV4cCI6MTY0ODYzMDM4Mn0.e67gnBudk4VDEW6co-9nB7s50PX0Ek6YZURymt8wWeI",
  "transactionId": "TRX_601c70939181441eba5dd49c1b8218ab",
  "orderBatches": [
    {
      "label": "FIX",
      "originalLabel": "BUY",
      "status": "PARTIALLYFILLED",
      "transactionId": "TRX_601c70939181441eba5dd49c1b8218ab",
      "variety": "regular",
      "buyAmount": 4538.02,
      "sellAmount": 0,
      "completedDate": "2022-03-30T07:53:25.357Z",
      "quantity": 7,
      "filled": 3,
      "batchId": "62440c71c1a71f7ee18a6398",
      "orders": [
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "COMPLETE",
          "quantity": 5,
          "tradingsymbol": "AMBUJACEM",
          "transactionType": "BUY",
          "filledQuantity": 5,
          "averagePrice": 302.018,
          "statusMessage": "NA",
          "errorCode": null
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "REJECTED",
          "transactionType": "BUY",
          "quantity": 1,
          "statusMessage": "RMS:Margin Exceeds,Required:x, Available:y for entity account across exchange across segment across product",
          "averagePrice": 1523.15,
          "filledQuantity": 0,
          "tradingsymbol": "COLPAL",
          "errorCode": "marginExceeded"
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "REJECTED",
          "transactionType": "BUY",
          "quantity": 4,
          "statusMessage": "RMS:Margin Exceeds,Required:x, Available:y for entity account across exchange across segment across product",
          "averagePrice": 376,
          "filledQuantity": 0,
          "tradingsymbol": "CROMPTON",
          "errorCode": "marginExceeded"
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "REJECTED",
          "transactionType": "BUY",
          "quantity": 1,
          "statusMessage": "RMS:Margin Exceeds,Required:x, Available:y for entity account across exchange across segment across product",
          "averagePrice": 1637.89,
          "filledQuantity": 0,
          "tradingsymbol": "ESCORTS",
          "errorCode": "marginExceeded"
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "COMPLETE",
          "quantity": 2,
          "tradingsymbol": "M&M",
          "transactionType": "BUY",
          "filledQuantity": 2,
          "averagePrice": 772.95,
          "statusMessage": "NA",
          "errorCode": null
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "COMPLETE",
          "quantity": 13,
          "tradingsymbol": "MANAPPURAM",
          "transactionType": "BUY",
          "filledQuantity": 13,
          "averagePrice": 114.00,
          "statusMessage": "NA",
          "errorCode": null
        },
        {
          "orderType": "MARKET",
          "product": "CNC",
          "exchange": "NSE",
          "status": "REJECTED",
          "transactionType": "BUY",
          "quantity": 1,
          "statusMessage": "RMS:Margin Exceeds,Required:x, Available:y for entity account across exchange across segment across product",
          "averagePrice": 1101.05,
          "filledQuantity": 0,
          "tradingsymbol": "SBILIFE",
          "errorCode": "marginExceeded"
        }
      ],
      "unplaced": []
    }
  ],
  "broker": "kite",
  "name": "Rising Rural Demand",
  "scid": "SCNM_0012",
  "source": "PROFESSIONAL",
  "iscid": "62440939317dea7eaaf3373e",
  "imageUrl": "https://assets.smallcase.com/images/smallcases/200/SCNM_0012.png"
}

🚧
statusMessage is not a standardised message across brokers
It is not always suitable to be displayed to end-users as-is. It would be helpful for product and support teams to investigate order failures.

🚧
Your code should have a fallback for any unexpected errorCode
New errorCode are expected to be introduced as broker integrations expand. Your code should have a fallback for any unexpected errorCode.

Order errors: placement and execution

Error sharing with the user ✨

Error sharing with the partner 🤝

Error codes

Sample response

Securities transaction

smallcase transaction

🚧
statusMessage is not a standardised message across brokers

🚧
Your code should have a fallback for any unexpected errorCode

Error sharing with the user ✨

Error sharing with the partner 🤝

Error codes

Sample response

Securities transaction

smallcase transaction

🚧statusMessage is not a standardised message across brokers

🚧Your code should have a fallback for any unexpected errorCode

🚧
statusMessage is not a standardised message across brokers

🚧
Your code should have a fallback for any unexpected errorCode