TronGrid uses API keys, daily quotas, and request frequency limits to protect service stability. Rate-limited requests usually return 429 or 403 and should be retried with backoff.
TronGrid uses API keys, daily quotas, and request frequency limits to protect service stability. Production requests should include TRON-PRO-API-KEY, and clients should implement retry, backoff, and caching strategies.
Specific quota and QPS may change depending on plan, network, endpoint type, and service policy. Do not hard-code fixed limits into business logic. Use the TronGrid console and current service responses as the source of truth.
Rate-limit dimensions
TronGrid may limit requests across multiple dimensions:
| Dimension | Description |
|---|---|
| API key | Each key has independent quota and frequency limits |
| Account or project | Multiple keys under the same account may share total quota |
| IP address | Requests without an API key or abnormal traffic may be limited by IP |
| Endpoint type | High-cost query endpoints may have stricter limits |
| Time window | Per-second, per-minute, and per-day windows may apply at the same time |
Common rate-limit behavior
| Scenario | Possible result | Recommended handling |
|---|---|---|
| API key included and quota is available | Request is processed normally | Continue monitoring latency and error rate |
| API key included but burst traffic is too high | 429 Too Many Requests | Reduce concurrency and retry with exponential backoff |
| API key included but daily quota is exhausted | Frequency is further limited or requests return errors | Reduce traffic, upgrade plan, or wait for quota reset |
| No API key | Strict rate limiting or rejection | Add TRON-PRO-API-KEY to production requests |
| Abnormally frequent polling | Temporary block or 403 / 429 | Stop polling, wait for unblock, then lower frequency |
Error responses
When rate-limited, V1 API may return a response similar to:
{
"success": false,
"error": "The key exceeds the frequency limit",
"statusCode": 429
}Standard node HTTP proxy APIs may return a simpler error body:
{
"Error": "The key exceeds the frequency limit"
}Do not rely on a single error message to detect rate limiting. Check the HTTP status code, error fields in the response body, and whether the request included the correct API key.
Retry and backoff strategy
Recommended handling:
- Use exponential backoff with jitter for
429, so multiple service instances do not retry at the same time. - For
403, first check the API key, security settings, and whether a temporary block was triggered. Do not retry at high frequency immediately. - Cache read APIs. Account state, Token information, and block statistics usually do not require millisecond-level refresh.
- Design polling around TRON block production. TRON produces a new block about every 3 seconds, so polling the latest block or events much faster than that is usually not useful.
- Use pagination and checkpoint-based scans for historical data. Do not request overly large ranges in a single call.
Increase API key access volume
If the current API key quota does not meet your business needs, you can apply for a higher quota or a custom plan through TronGrid. The current process is:
- Register and log in at TronGrid.
- Open the TronGrid Price page.
- Find the Custom Price section and click Contact US.
- Submit business information, expected request volume, main endpoint types, target networks, and use case.
- The TronGrid team evaluates the request based on business needs, traffic scale, and service resources, then adjusts the corresponding account or API key configuration.
Prepare the following information before applying:
| Information | Description |
|---|---|
| Use case | Wallet, exchange, DApp backend, data analytics, indexer, AI Agent, and so on |
| Target network | Mainnet, Shasta Testnet, or Nile Testnet |
| Main endpoints | Account transaction history, TRC-20 transfers, contract events, block statistics, and so on |
| Expected traffic | Peak QPS, daily request volume, and whether periodic batch jobs are involved |
| Current issue | Status codes, error messages, approximate time of rate limiting, and request pattern |
Quota increases are not automatic. The final result depends on TronGrid team's evaluation and actual configuration.
Reduce request volume
Common optimizations:
- Cache account and Token metadata locally.
- Merge high-frequency page requests in your backend instead of sending duplicate requests from browsers directly to TronGrid.
- Use events or block numbers as synchronization cursors and query only new ranges.
- Avoid having multiple service instances scan the same address or block range at the same time.
- Use separate API keys for different services, so abnormal traffic can be observed and limited independently.
Related resources
- API Key — create keys, choose network endpoints, and configure request headers
- Security settings — restrict key usage with allowlists and JWT
- TronGrid V1 API overview — V1 API categories and typical use cases
- TronGrid — TronGrid node service and extension API introduction