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 -

securities transaction: order status screensecurities transaction: order status screen

securities transaction: order status screen

smallcase transaction: order status screensmallcase transaction: order status screen

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:

  1. SDK response of trigger transaction method
  2. API for stocks order details and smallcase order details
  3. Stock order webhooks

📘

Refer to the sample order response (with error keys) added at the bottom of this page

Sample order response & enums will be updated across doc pages once the feature goes live

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.

  1. 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.

  2. 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

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.


Did this page help you?