> For the complete documentation index, see [llms.txt](https://docs.tronsave.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tronsave.io/developers/errors-and-rate-limits.md). # Errors & Rate Limits Every TronSave API endpoint shares the same rate-limiting policy and error-response shape. This page documents both so you can build robust retry and error-handling logic once and reuse it across all calls. ## Rate limits Most endpoints allow a default of **15 requests per second**. {% hint style="warning" %} The [Sell Resources](/developers/api-reference/sell-resources.md) endpoints are limited to **2–3 requests per second**. All other endpoints use the default of 15 requests per second. {% endhint %} The current limit for each endpoint is documented in its API reference page (for example, the [Create Order](/developers/api-reference/buy-resources/api-key/create-order.md) and [Estimate TRX](/developers/api-reference/buy-resources/api-key/estimate-trx.md) endpoints state `Rate limit: 15 requests per 1 second`). When you exceed the limit, the API returns **HTTP 429**: ```json { "error": true, "message": "Rate limit reached" } ``` {% hint style="info" %} Handle `429` by backing off and retrying. A simple exponential backoff (e.g., wait 1s, then 2s, then 4s) is usually sufficient to stay within the per-second budget. {% endhint %} ## Response shape Successful responses use a consistent envelope: `error` is `false`, `message` is `"Success"`, and the payload is under `data`. ```json { "error": false, "message": "Success", "data": { "orderId": "6818426a65fa8ea36d119d2c" } } ``` Error responses return a non-2xx HTTP status code. Most application errors use the same envelope with `error: true`, a machine-readable code embedded in `message` (e.g. `TSAS:106 API_KEY_REQUIRED`), and `data: null`: ```json { "error": true, "message": "TSAS:106 API_KEY_REQUIRED", "data": null } ``` Schema-validation failures are produced by the HTTP layer and use a different shape, naming the offending field in `message`: ```json { "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "body must have required property 'receiver'" } ``` ## Error codes The table below lists the error codes observed across the API, grouped by HTTP status. Use the **code** (the JSON key) for programmatic handling — the **message** text may change.
HTTPCodeMessage
400MISSING_PARAMSMissing some params in body
400INVALID_PARAMSSome params are invalid
400MIN_PRICE_INVALIDminPrice is less than the system's minimum price or is not in the correct format.
400INTERNAL_ACCOUNT_NOT_FOUNDinternal account does not exist
400INTERNAL_BALANCE_ACCOUNT_TOO_LOWBalance is not enough
400CANNOT_FULFILLEDThe order requires an immediate full match, but the system cannot fulfill 100% of it.
400MUST_BE_WAIT_PREVIOUS_ORDER_FILLEDA pending order with the same parameters already exists in the system.
400PRICE_EXCEED_MAX_PRICE_REQUIREDThe price of the order exceeds the maximum price accepted.
401API_KEY_REQUIREDMissing api key in headers
401INVALID_API_KEYapi key not correct
429RATE_LIMITRate limit reached
{% hint style="info" %} Not every code applies to every endpoint. For example, `CANNOT_FULFILLED` and `PRICE_EXCEED_MAX_PRICE_REQUIRED` are only returned when creating an order. Individual API reference pages list the codes specific to each endpoint. {% endhint %} ## Example error payloads {% tabs %} {% tab title="400 Bad Request" %} Schema validation (a required field is missing or invalid — the message names the field): ```json { "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request", "message": "body must have required property 'receiver'" } ``` Business-logic validation (returned by order-related endpoints) uses the standard envelope: ```json { "error": true, "message": "TSAS:xxx INTERNAL_BALANCE_ACCOUNT_TOO_LOW", "data": null } ``` {% endtab %} {% tab title="401 Unauthorized" %} Missing `apikey` header: ```json { "error": true, "message": "TSAS:106 API_KEY_REQUIRED", "data": null } ``` Invalid `apikey`: ```json { "error": true, "message": "TSAS:107 INVALID_API_KEY", "data": null } ``` {% hint style="info" %} The legacy v0 API omits the `data` field: `{"error": true, "message": "TSAS:107 INVALID_API_KEY"}`. {% endhint %} {% endtab %} {% tab title="404 Not Found" %} Wrong route or path: ```json { "message": "Route POST:/v2/... not found", "error": "Not Found", "statusCode": 404 } ``` {% endtab %} {% tab title="429 Too Many Requests" %} ```json { "error": true, "message": "Rate limit reached" } ``` {% endtab %} {% endtabs %} ## Handling common cases * **`401` (`API_KEY_REQUIRED` / `INVALID_API_KEY`)** — Check that the `apikey` header is present and correct. See [Authentication](/developers/authentication.md). * **`INTERNAL_BALANCE_ACCOUNT_TOO_LOW`** — Top up your [Internal Account](/concepts/glossary.md) before creating an order. * **`CANNOT_FULFILLED`** — The market cannot fill the order in full at the requested price. Lower expectations (e.g., enable `allowPartialFill`) or adjust `unitPrice`. * **`PRICE_EXCEED_MAX_PRICE_REQUIRED`** — The estimated price is above your `options.maxPriceAccepted`. Re-check the price with [Estimate TRX](/developers/api-reference/buy-resources/api-key/estimate-trx.md) before retrying. * **`429` (`RATE_LIMIT`)** — Back off and retry within your per-second budget. ## Next steps * [Authentication](/developers/authentication.md) — how to obtain and send your API Key. * [API Reference](/developers/api-reference.md) — per-endpoint parameters and responses. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tronsave.io/developers/errors-and-rate-limits.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.