# Errors and recovery

> JSON-RPC and TRON HTTP API error contracts with recovery actions.

Canonical page: https://rpc.aurpay.net/docs/errors

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](https://rpc.aurpay.net/docs/endpoint-free-rpc.md) 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](https://rpc.aurpay.net/docs/failsafe/circuit.md) 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

1. Copy the complete Access Point from the target Gateway.
2. Send the chain guide's verification request with an Active or Grace API Key.
3. Keep the App, Gateway, Endpoint, and Route enabled with an exact chain, network, and protocol match.
4. Run the Endpoint health check to validate the upstream URL and Provider credential.
5. Apply the recovery action for the Gateway code or HTTP status and honor `Retry-After` when present.
6. 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.

## Related

- [Endpoint-free RPC](https://rpc.aurpay.net/docs/endpoint-free-rpc.md)
- [Failsafe](https://rpc.aurpay.net/docs/failsafe.md)
- [Routing and reliability](https://rpc.aurpay.net/docs/reliability.md)
- [JSON-RPC](https://rpc.aurpay.net/docs/json-rpc.md)