API Standards

Shared rules and conventions for working with FYERS APIs.

Follow these conventions when building requests, handling responses, working with timestamps, interpreting errors, and implementing retries.

Base URLs

Use the host documented on the specific API page.
REST APIs and WebSocket services use different hosts.
Do not reuse a REST base URL for a socket connection.

Authentication

Transport security

FYERS APIs are built with security in mind to prevent unauthorised transactions. All API requests and responses are sent and received only over the HTTPS protocol.

Authorization header

After authentication you receive an access_token. Send your App ID and access token together as app_id:access_token in the HTTP Authorization header on every subsequent request.


curl -H "Authorization: app_id:access_token"
curl -H "Authorization: aaa-99:bbb"

Send an active access token on authenticated requests. Keep tokens private — never log them or ship them in client-side or public code. Use the exact format on the API page when a documented header differs.

Request and response format

Follow the method, URL, and fields on that API page.
Send required fields in the documented format.
Validate the response before using it in a trading workflow.

Success response

Attribute	Data Type	Description
`s`	string	`ok`
`code`	int	`200`
`message`	string	Empty string on success.
Additional key	object / list / int / string	Each request returns its own key based on the request.

Failure response

Attribute	Data Type	Description
`s`	string	`error`
`code`	int	Negative integer that identifies the specific error.
`message`	string	Error message that identifies the error.
HTTP header	int	HTTP status code. See Common API Error Codes.

HTTP status codes

Status code	Meaning
`200`	Request was successful.
`400`	Bad request — the request is invalid, or another client-side error occurred.
`401`	Authorization error — the user could not be authenticated.
`403`	Permission error — the user does not have the necessary permissions.
`429`	Rate limit exceeded — the user has been blocked for exceeding the rate limit.
`500`	Internal server error.

Status and error model

Read the response code and message together before deciding the next action. Common cases are success, invalid input, auth failure, rate limit and order rejection.

Use Appendix → Common API Error Codes for the standard description and next action of each app-level error code (the negative code values in a failure response).

Timestamps and timezones

Use the timestamp format shown on the API page.
Keep request, storage, and display handling consistent.
Do not mix timezone assumptions across systems.

Pagination

Use the pagination fields documented for that endpoint.
Continue paging until the required records are retrieved.
Stop when the page has no further results.

Rate limits and blocking

Every plan has per-second, per-minute and per-day request limits — see Plans & Rate Limits for the exact numbers per plan and API category. If the per-minute limit is exceeded more than 3 times in a day, the user is blocked from making further requests for the rest of that day.

Idempotency and retries

Retry only when it is safe.

Confirm account state before repeating order or position actions.
Check that the earlier request did not already succeed.
Do not blindly replay requests after timeouts or network errors.

How API pages are structured

Every API page follows the same structure, so you always know what to expect.

Understand — What the API does and when to use it.
Check access — Plan availability and access limits.
Prepare — Prerequisites and authentication.
Make the request — Method, URL and request parameters.
Read the response — Response fields and examples.
Handle errors — Error codes and recommended actions. See Common API Error Codes.