Routing and reliability
The Gateway checks Endpoint-free RPC first, then a Route connects the public entry point to one or more Endpoints. Endpoint selection, failover, and fallback retries apply when the Route has usable targets.
See RPC Failover for the product overview and Multi-Provider RPC for the upstream inventory model.
- Priority failover uses the configured Endpoint order; load balancing selects usable candidates by relative weight.
- Route filters remove disabled or incompatible Endpoints; Circuit can reject a selected candidate before an upstream attempt.
- Only retryable failures advance to another candidate within the configured attempt bound; valid upstream JSON-RPC application errors are final.
Routing strategies
| Strategy | Initial selection | Use it when |
|---|---|---|
| Priority failover | Follows the configured Endpoint order. | You have a preferred upstream and ordered backups. |
| Load balance | Selects eligible Endpoints randomly by relative weight. | Equivalent upstreams should share initial selections. |
Both strategies apply compatibility filtering and Circuit admission before an upstream attempt.
Priority failover
Uses Endpoints in configured order. It tries the next Endpoint only when the current target is filtered, blocked by its Circuit, or encounters a retryable failure.
Use this when you have an explicit primary and ordered backups. Health alone does not unconditionally change priority.
Load balance
Selects one eligible candidate randomly by relative weight. The normalized percentages are expected shares of initial selections while the eligible candidate set remains unchanged; short samples can vary.
Use this to share traffic across equivalent upstreams. Filters, Circuit rejection, and retryable failures remove candidates and renormalize the remaining weights, so actual upstream attempts can depart from the configured shares during failures. A single remaining candidate can still be selected, so load balancing is not an availability guarantee.
Candidate filtering
A Route keeps Endpoints that have:
- enabled state; and
- matching chain, network, and protocol.
After selection, Circuit is the runtime fault-admission authority. A rejected candidate is removed for that request, and the Route selects again from the remaining candidates without consuming an attempt.
Retries and failover
A retryable failure moves the request to the next candidate within a bounded number of attempts. A valid upstream JSON-RPC application error is final and does not trigger failover.
Failsafe covers attempt bounds, operation-aware failover, and Circuit behavior.
Rate limits
JSON-RPC and TRON HTTP API have independent capacity and may be limited by global, IP, Account, and App policies. Production RPS values are controlled by platform policy and are not fixed by this documentation.
- JSON-RPC: HTTP
200, error code-32029,data.retry_after_ms, and aRetry-AfterHeader. - TRON HTTP API: HTTP
429and aRetry-AfterHeader.
Retry with exponential backoff, random jitter, and a bounded attempt count.
Endpoint-free RPC and fallback
Endpoint-free RPC covers its explicit request shapes. A hit bypasses Endpoint selection; a miss proceeds to the Route. Configure a matching Endpoint-backed Route for stable fallback coverage.
Validate time-sensitive data according to chain semantics and use an Endpoint-backed Route for stable coverage across historical heights, slots, hashes, and cache refreshes. The TRON HTTP API uses Endpoint-free RPC for the two exact request shapes listed in Endpoint-free RPC.