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:

  1. SDK response of trigger transaction method
  2. API for stocks order details and smallcase order details
  3. 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.

  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

errorCodeDescription
adapterErrorGateway was unable to reach broker's systems
tradingSystemNotReadybrokers system is not accepting orders at the moment. Probably due to market being closed
checkHoldingsUsers' broker account does not have sufficient holdings that are allowed to be sold.
marginsExceededNot enough funds to place the order or above the set limits for the account.
orderUnmatchedNo buyers or sellers are available at the moment. This can happen due to liquidity issues or the stock hitting circuits.
circuitLimitExceededThe price specified is not within circuit limits set by the exchange
checkFreezeQtyEntered quantity is greater than the allowed (freeze) quantity
qtyNotMultipleOfLotQuantity does not meet lot requirements for this stock. More info
userNotLoggedInCould obtain authorization to place an order, the user may not be logged in or logged in session expired.
clientNotEnabledThe broker account doesn't have equity trading enabled
clientBlockedPlacing orders from this account is blocked.
exchgNotEnabledThe account is not allowed to place orders on the specified exchange
securityNotAllowedThe security is not allowed to be traded in this exchange
debtorNotAllowedThe user has a debit balance that needs to be cleared by adding more funds
sellNeedsAuthCouldn't obtain authorization to sell holdings
ASMGSMListTrading may be restricted in specified stocks as they are listed in the ASM or GSM category set by the exchange
stockTipsBlockedTrading may be restricted in specified stocks by the exchange on reports of unsolicited messages
networkErrorCouldn't fetch order status from the broker
kiteStockTipsBlockedTrading 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
kiteClientReactivationRequiredThe account needs to be reactivated due to inactivity for over 12 months.
kiteClientNotEnabledYour account is not setup for placing CNC orders.
kiteExchgNotEnabledYour account is not setup for placing orders on the exchange.
kiteASMGSMListTrading 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
kiteIllquidStocksTrading 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
exchangeMismatchThe 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.
intradayNotAllowedIntraday/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.
tradingSymbolThe trading symbol used is no longer valid.
omsMaintenanceBroker's order management system is under scheduled maintenance. Try placing the order after some time.
holdingsAuthorizationUser needs to authorize sell orders on CDSL for the stock
dealerLocationmappingKotak client accounts need to be mapped to the dealer branch before placing orders
stockBlockedSymbolNotFoundThe trading symbol used is no longer valid.
blockedNRIUser's account type does not support placing intraday orders
axisBlockednriUser's account type does not support placing intraday orders
kycPendingKYC verification has to be done for the demat account either because its newly opened or it has been inactive for >12 month
iciciKycPendingKYC verification has to be done for the demat account either because its newly opened or it has been inactive for >12 month
peakMarginDue 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
otherErrorOrder 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.