错误响应格式

所有错误均使用统一的 JSON 格式返回：

{
  "code": "error_code",
  "message": "错误描述信息",
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

字段	类型	说明
code	string	错误码
message	string	错误描述
request_id	string	唯一请求追踪 ID，排查问题时请提供此值

---

错误码列表

客户端错误 (4xx)

HTTP 状态码	错误码	说明	处理建议
400	invalid_request	请求格式错误（空请求体、无效 JSON 或非法的 JSON-RPC 格式）	检查请求体是否为合法的 JSON-RPC 2.0 格式
400	tx_method_required	在 /v1/tx 端点使用了非交易方法	查询请求请使用 /v1/rpc 端点
401	auth_required	未提供 API Key	在请求头中添加 X-User-ID: <your-api-key>
403	forbidden	访问被拒绝	检查您的 API Key 是否有效
403	feed_not_entitled	当前套餐不支持 Feed 功能	升级至 VIP1 或更高套餐
429	rate_limited	请求频率超过配额限制	读取响应头中的 Retry-After 值，等待指定秒数后重试
429	feed_limit_exceeded	Feed 连接数达到套餐上限	关闭已有的 Feed 连接后再建立新连接

服务端错误 (5xx)

HTTP 状态码	错误码	说明	处理建议
500	internal_error	服务内部错误	请稍后重试；若持续出现请联系技术支持
502	upstream_error	上游 Robinhood Chain 节点错误	请稍后重试
503	queue_full	交易提交系统繁忙（仅 /v1/tx）	请稍后重试
504	upstream_timeout	上游节点响应超时	请稍后重试

---

常见问题排查

现象	可能原因	解决方法
所有请求返回 401	未携带 X-User-ID 请求头	在请求头中添加 X-User-ID: <your-api-key>
频繁收到 429	请求频率超过套餐限制	降低请求频率，或升级至更高级套餐
Feed 连接返回 403	Free 套餐不包含 Feed 功能	升级至 VIP1 或 VIP2 套餐
RPC 请求返回 502	上游 Robinhood Chain 节点暂时不可用	等待片刻后重试
RPC 请求返回 504	上游节点响应超时	等待片刻后重试，或检查网络状况
交易提交返回 503	系统繁忙	等待片刻后重试

排查问题时，请务必记录响应中的 request_id，联系技术支持时提供此 ID 可大幅加快定位速度。