Errors & Rate Limits

Rate limits, HTTP status codes, and error payloads returned by the TronSave API.

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.

The Sell Resources endpoints are limited to 2–3 requests per second. All other endpoints use the default of 15 requests per second.

The current limit for each endpoint is documented in its API reference page (for example, the Create Order and Estimate TRX endpoints state Rate limit: 15 requests per 1 second).

When you exceed the limit, the API returns HTTP 429:

{
    "error": true,
    "message": "Rate limit reached"
}

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.

Response shape

Successful responses use a consistent envelope: error is false, message is "Success", and the payload is under data.

{
    "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:

{
    "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:

{
    "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.

HTTP	Code	Message
400	MISSING_PARAMS	Missing some params in body
400	INVALID_PARAMS	Some params are invalid
400	MIN_PRICE_INVALID	minPrice is less than the system's minimum price or is not in the correct format.
400	INTERNAL_ACCOUNT_NOT_FOUND	internal account does not exist
400	INTERNAL_BALANCE_ACCOUNT_TOO_LOW	Balance is not enough
400	CANNOT_FULFILLED	The order requires an immediate full match, but the system cannot fulfill 100% of it.
400	MUST_BE_WAIT_PREVIOUS_ORDER_FILLED	A pending order with the same parameters already exists in the system.
400	PRICE_EXCEED_MAX_PRICE_REQUIRED	The price of the order exceeds the maximum price accepted.
401	API_KEY_REQUIRED	Missing api key in headers
401	INVALID_API_KEY	api key not correct
429	RATE_LIMIT	Rate limit reached

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.

Example error payloads

400 Bad Request

Schema validation (a required field is missing or invalid — the message names the field):

{
    "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:

{
    "error": true,
    "message": "TSAS:xxx INTERNAL_BALANCE_ACCOUNT_TOO_LOW",
    "data": null
}

401 Unauthorized

404 Not Found

429 Too Many Requests

Handling common cases

• 401 (API_KEY_REQUIRED / INVALID_API_KEY) — Check that the apikey header is present and correct. See Authentication.

• INTERNAL_BALANCE_ACCOUNT_TOO_LOW — Top up your Internal Account 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 before retrying.

• 429 (RATE_LIMIT) — Back off and retry within your per-second budget.

Next steps

• Authentication — how to obtain and send your API Key.

• API Reference — per-endpoint parameters and responses.