Errors and recovery
Use the response format, status, and code to select the matching recovery action.
JSON-RPC errors
For an ID-bearing request, JSON-RPC errors normally use HTTP 200. Read the JSON-RPC error.code and use the corresponding recovery action.
| Code | Message | Action |
|---|---|---|
-32700 | Parse error. | Check JSON encoding and body completeness |
-32600 | Invalid Request. | Send one strict JSON-RPC 2.0 object |
-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. | Use an exact Endpoint-free RPC request shape or add a Route Endpoint for stable fallback |
-32005 | Endpoint request failed. | Check upstream connectivity, credentials, timeout, Route Endpoints, and upstream HTTP status |
-32029 | Rate limit exceeded. | Back off using Retry-After or retry_after_ms |
-32603 | Internal error. | Preserve the request context for escalation |
Gateway-generated errors include data.type: "gateway_error". Upstream JSON-RPC errors preserve the upstream code and message.
A valid Notification omits id and receives HTTP 204 with no JSON-RPC Response. An explicit "id": null is an ordinary request that receives a response. The 204 confirms only response suppression; it does not establish successful routing or forwarding, upstream acceptance or processing, method or transaction success, or network acceptance.
Recover from -32004
Apply this configuration checklist:
- Use an exact method and parameter form from Endpoint-free RPC for cache-eligible reads.
- Configure at least one enabled Endpoint with an exact chain, network, and protocol match.
- Attach the Endpoint to the Gateway’s default Route and keep the Gateway enabled.
- Confirm the Endpoint health check and Circuit recovery state.
Configure an Endpoint-backed Route for reliable coverage, additional methods, and writes.
TRON HTTP API status codes
| HTTP | Meaning | Action |
|---|---|---|
400 | Invalid request or Content-Length | Check request formatting |
401 | Authentication failed | Check the API Key and its placement (Authorization header or URL path) |
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 your RPC Gateway administrator 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 the request context for escalation |
Gateway responses for /wallet/* and /walletsolidity/* use an Error field. Responses for /v1/* use Success, Error, and StatusCode fields. Upstream status codes and bodies are preserved, so use the body shape, request time, and Endpoint observations together.
Recovery checklist
- Copy the complete Access Point from the target Gateway.
- Send the chain guide’s verification request with an Active or Grace API Key.
- Keep the App, Gateway, Endpoint, and Route enabled with an exact chain, network, and protocol match.
- Run the Endpoint health check to validate the upstream URL and Provider credential.
- Apply the recovery action for the Gateway code or HTTP status and honor
Retry-Afterwhen present. - For escalation, provide the UTC time, Host, JSON-RPC
id, method, Gateway code, and redacted response to your RPC Gateway administrator or existing support contact.
Management API responses use a separate trace_id; include it when escalating a Management API request. Keep API Keys, PATs, and credential-bearing URLs redacted.