Errors and troubleshooting

First distinguish HTTP transport failures, Gateway-generated errors, and upstream application errors.

JSON-RPC errors

Except for HTTP-layer failures such as an unmatched Host or an oversized body, JSON-RPC errors normally use HTTP 200:


{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32004,
    "message": "No available Endpoint.",
    "data": {"type": "gateway_error"}
  }
}

Code	Message	Action
`-32700`	Parse error.	Check JSON encoding and body completeness
`-32600`	Invalid Request.	Send one strict JSON-RPC 2.0 object; do not send a batch
`-32001`	Authentication failed.	Check the Key, Bearer format, Key state, and App state
`-32002`	Gateway not found.	Copy the target network Access Point again
`-32003`	Gateway is disabled.	Enable the App and target Gateway
`-32004`	No available Endpoint.	Check the Accelerator method and parameters; add a route Endpoint for reliable fallback
`-32005`	Endpoint request failed.	Check upstream connectivity, credentials, timeout, and retry policy
`-32029`	Rate limit exceeded.	Back off using `Retry-After` or `retry_after_ms`
`-32603`	Internal error.	Keep the request time, Host, and request ID and contact the platform operator

Upstream JSON-RPC errors keep upstream code and message values and should not be interpreted as Gateway codes.

Troubleshoot `-32004`

This error does not only mean that a route is empty. It can also mean:

the request is outside the Accelerator method set;
the method is eligible but its parameters do not match the cache policy;
no cache entry exists, or it expired, for that chain, network, height, slot, or block hash;
Accelerator has no usable result and the route has no Endpoint for fallback.

Do not assume that repeating the request will produce a hit. Check the method and parameters first. Configure an Endpoint for reliable coverage, more methods, or writes.

TRON HTTP API status codes

HTTP	Meaning	Action
`400`	Invalid request or Content-Length	Check request formatting
`401`	Authentication failed	Check the App Key and Bearer/Path Key placement
`404`	Host, Gateway, or path not found	Check the network Host and allowed path family
`405`	Method not allowed	Use GET or POST only
`408`	Body-read timeout	Check client upload and network behavior
`413`	Request body too large	Reduce the request or ask the operator for the deployed limit
`429`	Rate limited	Back off using `Retry-After`
`502`	Endpoint attempts failed	Inspect upstreams and Route configuration
`503`	Gateway disabled or no available Endpoint	Enable the Gateway and configure a matching HTTP API Endpoint
`500`	Internal Gateway error	Preserve request context and contact the operator

Gateway errors for /wallet/* and /walletsolidity/* use:


{"Error":"No available Endpoint."}

Gateway errors for the /v1/* path family use:


{"Success":false,"Error":"No available Endpoint.","StatusCode":503}

Upstream status codes and bodies are preserved, so the same HTTP status can originate upstream. Use the response body, request time, and Endpoint observations to distinguish it.

Troubleshooting sequence

Copy the Access Point again; do not guess the Host.
Test the simplest read method from the Accelerator table to validate the Key and Gateway.
For -32004, check the method, parameters, and whether reliable fallback is required.
When using an Endpoint, confirm that the App, Gateway, and Endpoint are enabled.
Confirm that the Route has at least one Endpoint with an exact chain, network, and protocol match.
Run the Endpoint health check separately to validate the upstream URL and provider credentials.
Inspect Retry-After, the Gateway error code, and the upstream error message.
If escalation is required, provide UTC time, request Host, JSON-RPC id, method, and complete error. Never provide the App API Key.

Errors and troubleshooting

JSON-RPC errors

Troubleshoot -32004

TRON HTTP API status codes

Troubleshooting sequence

Troubleshoot `-32004`