错误与排查

先区分三类失败：HTTP 传输错误、Gateway 生成的错误、上游节点返回的业务错误。

JSON-RPC 错误

除 Host 不匹配、请求体超限等 HTTP 层失败外，JSON-RPC 错误通常使用 HTTP 200：


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

Code	Message	处理建议
`-32700`	Parse error.	检查 JSON 编码和请求体是否完整
`-32600`	Invalid Request.	发送单个严格 JSON-RPC 2.0 对象；不要发送 batch
`-32001`	Authentication failed.	检查 Key、Bearer 格式、Key 状态和 App 状态
`-32002`	Gateway not found.	从控制台重新复制目标网络的 Access Point
`-32003`	Gateway is disabled.	启用 App 和目标 Gateway
`-32004`	No available Endpoint.	核对 Accelerator 方法和参数；需要稳定回源时为 route 添加 Endpoint
`-32005`	Endpoint request failed.	检查上游连通性、鉴权、超时和 Route 重试策略
`-32029`	Rate limit exceeded.	按 `Retry-After` 或 `retry_after_ms` 退避
`-32603`	Internal error.	保留请求时间、Host、请求 ID，联系平台管理员

上游返回的 JSON-RPC error 保留上游 code/message，不应按 Gateway code 解释。

排查 `-32004`

这个错误不只表示 route 为空。它也可能表示：

请求不在免 Endpoint 调用的方法范围内；
方法受支持，但参数形式不符合缓存策略；
对应链、网络、高度、Slot 或区块 Hash 的缓存不存在或已过期；
Accelerator 暂时没有可用结果，且 route 没有可回源的 Endpoint。

不要假设重复请求一定会命中。先按 Accelerator 表格核对方法和参数；需要稳定覆盖、更多方法或写入能力时配置 Endpoint。

TRON HTTP API 状态码

HTTP	含义	处理建议
`400`	请求或 Content-Length 无效	检查请求格式
`401`	鉴权失败	检查 App Key 和 Bearer/Path Key
`404`	Host、Gateway 或路径不存在	检查网络 Host 和允许的路径族
`405`	方法不允许	只使用 GET 或 POST
`408`	请求体读取超时	检查客户端上传和网络
`413`	请求体过大	缩小请求，或联系管理员确认部署限制
`429`	被限流	按 `Retry-After` 退避
`502`	Endpoint 尝试失败	检查上游和 Route 配置
`503`	Gateway 禁用或没有可用 Endpoint	启用 Gateway，配置匹配的 HTTP API Endpoint
`500`	Gateway 内部错误	保留请求上下文并联系管理员

/wallet/* 与 /walletsolidity/* 的 Gateway 错误格式：


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

/v1/* 路径族的 Gateway 错误格式：


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

上游响应的状态码和正文会保留，因此同一个 HTTP 状态可能来自上游。结合响应正文、请求时间和 Endpoint 观测定位问题。

快速排查顺序

从控制台重新复制 Access Point，不要手工猜测 Host。
用 Accelerator 表格中的最简单只读方法验证 Key 和 Gateway。
若返回 -32004，核对方法、参数以及是否必须稳定回源。
使用 Endpoint 时，确认 App、Gateway、Endpoint 都已启用。
确认 Route 至少包含一个链、网络、协议完全匹配的 Endpoint。
单独运行 Endpoint health check，验证上游地址和供应商鉴权。
检查 Retry-After、Gateway error code 和上游 error message。
仍无法定位时，提供 UTC 时间、请求 Host、JSON-RPC id、method 和完整错误；不要提供 App API Key。

错误与排查

JSON-RPC 错误

排查 -32004

TRON HTTP API 状态码

快速排查顺序

排查 `-32004`