How errors are surfaced across the API, common emsg values, and recommended retry behavior.
Overview
Shoonya APIs do not use HTTP status codes to signal application-level failures — a request can return HTTP 200 and still represent a failed operation. Always check the stat field in the response body first, per API Structure, before treating a response as successful.
Response shape
Field
Values
Description
stat
Ok / Not_Ok
Present on every response. Not_Ok means the call failed at the application level, regardless of HTTP status.
emsg
string
Present only when stat is Not_Ok. Human-readable, not a stable error code — match on substring, not exact string, since wording can vary slightly by cause.
The account isn't provisioned for API access at all.
Contact support/onboarding to enable API access on the account before calling any endpoint.
Invalid IP / IP-related
The request originated from an IP address not whitelisted for this account.
Confirm your outbound IP is registered — this is coordinated with the internal team (Akshay handles IP whitelisting) before API access will accept traffic from a new address. Not retryable until the IP is added.
Invalid Input : INVALID_VERIFIER
The OAuth code verifier (PKCE) sent during token exchange doesn't match the one used to generate the original auth code/challenge.
Regenerate the code verifier/challenge pair and restart the OAuth login flow from the beginning — a stale or reused verifier from a previous login attempt cannot be reused.
Back off and retry — see Retry Guidance below. Do not retry immediately in a tight loop.
Server Timeout
The backend didn't respond within its internal timeout window — transient, not caused by the request itself.
Safe to retry once after a short delay; if it persists, treat as a service issue rather than a client bug.
Invalid Input (general)
A required field is missing, malformed, or fails validation (bad exch/tsym, wrong type, out-of-range price, etc.).
Check the field list and coded values on the specific endpoint's page — see Exchange Segment Codes, Order Type Codes. Not retryable without changing the request.
Overview
Shoonya APIs do not use HTTP status codes to signal application-level failures — a request can return
HTTP 200and still represent a failed operation. Always check thestatfield in the response body first, per API Structure, before treating a response as successful.Response shape
statOk/Not_OkNot_Okmeans the call failed at the application level, regardless of HTTP status.emsgstatisNot_Ok. Human-readable, not a stable error code — match on substring, not exact string, since wording can vary slightly by cause.Common error categories
Invalid Session Key/Session ExpiredUser Not enabled on : APIInvalid IP/ IP-relatedInvalid Input : INVALID_VERIFIERRate_LimitedServer TimeoutInvalid Input(general)exch/tsym, wrong type, out-of-range price, etc.).Insufficient Funds/ margin-relatedRelated
See Rate Limits for quota-specific throttling details and Glossary for term definitions used in error messages.