Errors and recovery
Use the response format, status, and code to select the matching recovery action.
Response negotiation errors
An empty HTTP 406 means the Gateway cannot return an acceptable response encoding. Rejecting all available encodings, such as Accept-Encoding: *;q=0, prevents the call from executing. If incompatibility is discovered after execution—for example, a no-transform response when identity is forbidden—the call may already have taken effect.
Inspect HTTP status before parsing JSON, and correct the accepted encodings. Do not automatically retry writes after a 406; check the operation’s outcome first. See Response compression.
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 |
-32007 | Chain access is not allowed. | Use a chain enabled for your account |
-32008 | Monthly traffic limit exceeded. | Check the account’s monthly response allowance; see the recovery guidance below |
-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.
HTTP API status codes
These status codes apply to HTTP API traffic for TRON Mainnet and Nile.
| 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) |
403 | Chain access is not allowed | Use a chain enabled for your account |
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 or monthly response allowance exceeded | Use Retry-After when present for rate limiting; for Monthly traffic limit exceeded., follow the monthly allowance guidance below |
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 |
Except for the empty negotiation response described above, 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.
Monthly allowance recovery
-32008 or a Gateway HTTP 429 with Monthly traffic limit exceeded. means the account has exhausted its allowance or the response does not fit its remaining allowance. All Apps and Keys on the account share it; rotating a Key does not reset it. Ask your administrator about the configured allowance, use a smaller read response if capacity remains, or wait for the next UTC month.
The upstream may already have processed the request before the Gateway detects that the response does not fit. Check a write’s outcome before retrying it. A rejected response is not partially delivered. See Monthly response allowance for the counting rules.
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.