JSON-RPC 与 Data API 错误码参考

查询各服务返回的错误码、机器可读reason与重试策略，覆盖JSON-RPC与Data API等全部服务；被拒绝的调用不计费，响应中的docs_url会指向本页稳定锚点，完整错误目录可从/errors.json读取。

本参考文档收录 BlockVectra 服务的完整错误码与机器可读原因码（reason），明确标示被拒绝调用的计费规则、重试策略、退避时间以及面向 AI Agent 与自动化客户端的建议处理动作。

如需机器读取，可通过 /errors.json 获取完整的 JSON 格式错误目录。错误响应中携带的 docs_url 直接链接到本页面的稳定锚点：https://docs.blockvectra.com/en/errors/#<reason>（无 reason 的错误使用错误码锚点，如 #<code-number>）。

JSON-RPC 错误

HTTP	错误码	原因码	含义	是否计费	能否重试	等待时间（Retry-After）	Agent 建议动作
401	-32024	`missing_api_key`	请求缺少 API key，未在请求路径或请求头中提供	否	否	—	JSON-RPC 接口（/v1/{chain}）在请求路径（/v1/{chain}/<api_key>）或 x-api-key 请求头中传入 API key；Data API（/v1/data/）与充值接口（/v1/topup/）仅接受 x-api-key 请求头。
401	-32024	`invalid_api_key`	API key 未知、已停用或已吊销：JSON-RPC 与 Data API 均返回 HTTP 401 和 invalid_api_key 错误信封（JSON-RPC：error.code 为 -32024、error.data.reason 为 invalid_api_key；Data API：error.code 与 error.data.reason 均为 invalid_api_key）。	否	否	—	检查 key，必要时在控制台或用程序化开户重新登录建新 key（链接「会话或 key 丢了怎么办」小节）。
403	-32025	`key_expired`	API key 的有效期已过；需在控制台创建新 key	否	否	—	API key 已到期；在控制台或通过程序化开户创建新 key。
403	-32025	`key_cap_exhausted`	API key 的终身 CU 限额（创建时在 cu_cap 中设置）已用尽；需在控制台创建新 key	否	否	—	API key 终身 CU 上限已耗尽；在控制台或通过程序化开户创建新 key。
503	-32021	`auth_unavailable`	服务端临时无法校验 key，不是你的 key 有问题	否	是	遵循 Retry-After 响应头（秒）	服务端临时无法校验 key，不是你的 key 有问题；可重试，按 Retry-After 等待后重试，不要因此重建 key。
404	-32600	`unknown_chain`	请求的链标识不存在或不受支持	否	否	—	通过 GET /v1/chains 或 list_chains 工具获取受支持的链列表，核对 URL 路径中的链名。
404	unknown_endpoint	`unknown_endpoint`	Data API 请求方法与路径不匹配任何已知操作	否	否	—	核对请求方法与 URL 路径是否符合 Data API 文档要求。
200	-32700	`parse_error`	JSON 解析错误，请求体不是合法的 JSON 语法	否	否	—	核实请求体为合法的 JSON 语法后再发送。
200	-32600	`invalid_request`	JSON-RPC 请求格式不合法、成员名存在二义性或不是合法的对象/数组	否	否	—	检查请求体结构；修正 jsonrpc: '2.0'、id 与 method 字段后再发送。
200	-32602	`invalid_params`	方法参数不合法（如不支持的 tracer 或超时时间超限）	否	否	—	调整方法参数；核对该链支持的 tracer 列表与超时限制。
200	-32602	`logs_range_too_large`	eth_getLogs 查询的区块跨度超过该链允许的上限	否	否	—	缩窄日志查询的区块范围至 GET /v1/chains 中的 max_logs_block_range 上限以内。
429	-32005	`public_rate_limit`	公开端点的请求频率超出上限	否	是	遵循 Retry-After 响应头（秒）	按 Retry-After 响应头等待后重试，或带上 API key 请求（免费获取）。
429	-32005	`public_pool_busy`	公开端点暂时繁忙	否	是	遵循 Retry-After 响应头或等待数秒后退避重试	退避后重试，或带上 API key 请求（免费获取）。
200	-32601	`method_not_public`	该方法不在公开端点支持的方法列表中	否	否	—	改用公开端点支持的方法，或带上 API key 请求（免费获取）。
200	-32601	`method_not_allowed`	方法在该链上不可用或已被策略禁用	否	否	—	通过 GET /v1/chains 查询该链的 methods.allow 与 methods.deny 策略确认支持的方法。哪些链不支持发送交易由 GET /v1/chains 的 methods.allow 决定。
200	-32601	`subscription_not_available`	目标链不提供该 WebSocket 订阅	否	否	—	通过 GET /v1/chains 查看该链支持的 subscriptions 订阅类型。
200	-32602	`logs_filter_required`	logs 订阅须指定合约地址（address）或 topic0（topics 的第一个位置非空）	否	否	—	在 logs 过滤参数中指定 address 或非空的 topic0。
200	-32600	`batch_too_large`	批量请求包含的调用数超过单批上限	否	否	—	将批量请求拆分为更小的批次，使单批调用数在上限以内。
413	request_too_large	`request_too_large`	Data API 请求体大小超过上限	否	否	—	减小请求体体积后再发送。
200	-32000	`not_found`	请求的交易、区块或资源不存在	否	否	—	若为刚广播的交易或最新出块，等待链同步后重试；否则核对区块号或哈希值。
200	-32011	`state_window`	历史状态超出节点保留的最长区块窗口	否	否	—	仅查询 GET /v1/chains 中 state_window_blocks 范围内的区块，或改用 Data API 查询历史数据。
200	-32011	`range_not_indexed`	请求的历史区间尚未完整索引	否	否	—	将历史查询缩小至已索引的区间，不要原样重试未覆盖的区间。
200	-32011	`history_not_ready`	请求的近期历史数据尚未完成索引	否	是	等待索引追上目标数据；若有 error.data.retry_after_seconds，按其等待	等待索引追上后重试；若返回 error.data.retry_after_seconds，按指定秒数等待。
429	-32005	`key_rate_limit`	API key 的计算单元（CU）速率上限超限	否	是	遵循 Retry-After 响应头（秒）	休眠 Retry-After 指定的秒数后重试，或平摊请求流量。
429	rate_limited	`rate_limited`	接口或 GET /v1/account 请求频率超限（GET /v1/account 每个 key 每秒最多 5 次请求）	否	是	遵循 Retry-After 响应头（秒）	休眠 Retry-After 指定的秒数后重试。
429	-32005	`concurrency_limit`	在途并发请求数超过上限	否	是	遵循 Retry-After 响应头或等待当前调用完成	限制客户端并发池大小，等待已有请求完成。
429	-32005	`free_plan_call_limit`	免费套餐每秒调用次数上限超限	否	是	等待 1 秒后重试	降低请求发送频率，或充值升级为付费账户解锁更高吞吐量。
429	-32022	`request_exceeds_burst`	单次请求的 CU 权重超过单 key 突发上限容量	否	否	—	无需等待（等待不会成功）；须拆解批量请求或降低方法参数以适应突发容量。
429	-32022	`free_plan_batch_too_large`	单批调用数超过免费套餐每秒调用次数限制	否	否	—	无需等待；须将单批请求调用数拆小至免费套餐限额以内，或进行充值。
429	-32005	`ws_connection_limit`	该 key 或账户的 WebSocket 连接数已达上限	否	否	—	关闭闲置的 WebSocket 连接或复用已有连接。
200	-32022	`subscription_limit`	当前连接持有的订阅数（或 newHeads 订阅数）已达上限	否	否	—	退订不需要的现有订阅，或开启新的连接。
200	-32005	`ws_filter_capacity`	日志过滤器容量已满	否	否	—	退订现有 logs 订阅或使用更窄的过滤规则。
200	-32026	`ws_push_overloaded`	积压的推送通知过多，暂时无法接受新订阅	否	是	使用退避稍后重试，或重新建立连接	结合指数退避重试 eth_subscribe，或重新建立连接；已建立的订阅不受影响，继续接收通知。
200	-32005	`overloaded`	服务暂时过载	否	是	等待数秒并使用指数退避重试	结合抖动进行退避后重试请求。
402	-32020	`balance_exhausted`	账户余额不足或已耗尽；余额已知时 error.data 附带 balance_units 与 balance_cu	否	否	—	链上充值：在控制台或通过 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）获取充值地址，详见Agent 充值指南，或在控制台使用额度重置机会（如符合条件）。余额已知时 error.data 附带 balance_units（透支时可为负）与 balance_cu。
402	-32020	`free_grant_exhausted`	免费套餐周期额度已耗尽；余额已知时 error.data 附带 balance_units 与 balance_cu	否	否	—	链上充值：在控制台或通过 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）获取充值地址，详见Agent 充值指南、在控制台使用额度重置机会，或等待下一个周期补足额度。余额已知时 error.data 附带 balance_units（透支时可为负）与 balance_cu。
503	-32021	`billing_unavailable`	计费状态暂不可确认（新创建 key 正在同步或服务暂时繁忙）	否	是	遵循 Retry-After 响应头（秒）	非余额问题，新创建的 key 通常数秒内完成同步；按 Retry-After 等待后重试即可。
200	-32010	`node_syncing`	底层链节点正在同步中，调用暂时不可用	否	是	等待数秒后重试	等待节点同步完成，或查询 GET /v1/status 查看状态。
200	-32603	`upstream_unavailable`	底层链节点暂不可用、应答超时或返回畸形响应	否	是	等待数秒后重试	退避重试；可通过 GET /v1/status 查看节点健康度。
504	504	`upstream_timeout`	底层数据服务未在时限内应答	否	是	稍后重试	结合指数退避稍后重试请求。
200	-32000	`response_too_large`	底层节点返回的响应体超过服务端大小上限	否	否	—	缩窄查询范围（如缩小 eth_getLogs 区块区间或减少 trace 请求范围）。
200	-32603	`internal_error`	处理请求时发生内部错误	否	否	—	稍后重试；若持续失败请记录时间并联系支持团队。
200	4444	—	请求的区块已被底层节点裁剪	否	否	—	目标区块已超出节点的裁剪保留期，可改用 Data API 获取历史区块信息。
200	-32000	—	底层节点历史状态不存在或数据已被裁剪	否	否	—	缩窄查询到状态窗口以内，或改用 Data API 查询历史数据。
200	-32002	—	底层节点批量执行超时	否	是	等待数秒后使用较小的批次重试	减少单批调用数量后重试。
200	-32003	—	底层节点批处理响应体过大	否	否	—	拆分批次以减小单个响应体大小。
200	-32601	—	方法在该链上不可用或已被策略禁用	否	否	—	通过 GET /v1/chains 查询该链的 methods.allow 与 methods.deny 策略确认支持的方法。哪些链不支持发送交易由 GET /v1/chains 的 methods.allow 决定。
200	-32603	—	处理请求时发生内部错误	否	是	稍后重试	稍后重试；若持续失败请记录时间并联系支持团队。
200	-32600	—	批量请求被底层节点整体放弃拒绝	否	否	—	检查批次中各调用的参数规范；拆分后重试。
200	*	—	底层节点执行层返回的业务错误（如合约执行回滚 execution reverted、节点参数校验拒绝）	是	否	—	节点已执行计算并按方法权重计费。检查回滚原因或调用参数，切勿盲目原样重试。
408	408	—	从收完请求头到返回响应超过 35 秒超时	可能	是	读请求等待数秒后重试	已转发给节点的调用在节点应答后照常计费。读请求可退避重试；写请求（如 eth_sendRawTransaction）须先按交易哈希查状态，切勿盲目重发。

WebSocket 关闭码

WebSocket 连接关闭码与客户端建议处理动作。

错误码	原因码	含义	能否重试	等待时间（Retry-After）	Agent 建议动作
1001	—	连接空闲超时断开	是	根据需要重新连接	根据需要重新连接。
1003	—	不支持二进制数据帧	否	—	切勿盲目自动重连；仅发送 UTF-8 文本帧。
1009	—	单条请求消息体积超过 1 MiB 上限	否	—	切勿盲目自动重连；拆分大请求以满足 1 MiB 限制。
1012	—	服务重启维护	是	退避后重新连接	结合抖动退避重新建立连接，重新订阅并补全遗漏数据。
1013	—	目标链不可用或服务过载	是	使用指数退避后重新连接	使用带抖动的全指数退避重新连接，重新订阅并回溯补全遗漏数据。
4402	—	账户余额不足	否	—	切勿盲目自动重连；链上充值：在控制台或通过 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）获取充值地址，详见Agent 充值指南，或在控制台使用额度重置机会（如符合条件）。
4404	—	API key 无效、已停用或已吊销	否	—	切勿盲目自动重连；在控制台核验或轮换 API key 后再连接。
4408	—	会话推送队列超过 512 KiB（524,288 字节）时服务端关闭连接并丢弃待发通知；客户端可能收不到关闭帧（浏览器报 1006），意外断开按 4408 处理。	是	退避重连，并减少订阅或加快读取	意外断开（没收到关闭帧，浏览器报 1006）按 4408 处理：退避重连，并减少订阅或加快读取；重新建立订阅并通过 eth_getLogs 补全数据。
4429	—	推送消息速率超出上限	是	减少订阅或退避重连	减少订阅数量或退避后重连。
4503	—	计费服务暂时不可用	是	使用指数退避后重新连接	使用全抖动指数退避重新连接并重新订阅。

Data API 错误

区块链 Data API 端点（/v1/data/{chain}/）返回的结构化错误。

HTTP	错误码	原因码	含义	是否计费	能否重试	等待时间（Retry-After）	Agent 建议动作
400	bad_request	—	查询参数重复、查询字符串格式非法或请求格式错误	否	否	—	检查查询参数；确保 limit 等参数只出现一次，并核对参数格式。
409	not_indexed_yet	—	请求的区块号或窗口超过 as_of_block，或哈希解析出的区块高于 as_of_block（除尚无区块的链外附带 indexed_through）	否	是	等待数秒至 indexed_through 到达目标区块	轮询等待至目标区块或 to_block 不高于 indexed_through，或等待该链开始写入区块。
409	window_too_large	—	区块窗口跨度超过 100,000 块且未设置 clamp=true	否	否	—	缩窄区块区间至 100,000 块以内，或在查询参数中传入 clamp=true。
409	too_many_pools	—	该代币命中的流动性池超过 200 个，须改按池维度查询	否	否	—	按具体的流动性池地址查询，而非按代币维度全量匹配。
409	span_exceeded	—	请求的时间跨度超过 90 天上限	否	否	—	将 from_time 与 to_time 的时间跨度缩窄至 90 天以内。
422	no_coverage	—	该链不支持该特性，或请求的区块早于历史覆盖起点	否	否	—	查询前查看 GET /v1/data/chains 的 `features` 与 `coverage.from_block`（或免费的 GET /v1/status 的 `data_features`）。
503	unavailable	—	数据服务暂时不可用	否	是	等待数秒并使用指数退避重试	使用指数退避稍后重试。
402	insufficient_balance	—	付费余额或免费额度已耗尽；余额已知时 error.data 附带 balance_units 与 balance_cu	否	否	—	链上充值：在控制台或通过 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）获取充值地址，详见Agent 充值指南，或等待免费额度补足。
429	cost_exceeds_burst	—	单次请求的开销超过该 key 的突发容量	否	否	—	把请求拆小；原样重试永远不会成功。
503	gateway_overloaded	—	Data API 当前可用容量不足	否	是	Retry-After：1 秒	降低本账户各 key、各链的并发请求数，按 Retry-After 等待后重试；error.data.reason 为 null。

控制台、账户与水龙头 API 错误

管理端点、认证接口与水龙头返回的错误。

HTTP	错误码	原因码	含义	是否计费	能否重试	等待时间（Retry-After）	Agent 建议动作
409	topup_disabled	—	充值暂停或当前没有可用的充值网络；新地址无法分配，但已分配的地址仍归该账户	否	否	—	通过 GET /v1/topup/status 查询充值状态；待充值服务恢复后重试。
503	deposit_unavailable	—	暂时无法分配充值地址；按 Retry-After 响应头重试	否	是	遵循 Retry-After 响应头（秒）并使用指数退避重试	按 Retry-After 响应头时间重试，使用指数退避策略。
400	invalid_request	`invalid_username`	用户名去除首尾空白后超过 64 个 Unicode 字符，或含控制字符（Cc）或孤立代理字符（Cs）	否	否	—	首尾空白会被去除，空结果按 null 处理；其他用户名最多 64 个 Unicode 字符，且不能含控制字符（Cc）或孤立代理字符（Cs）。
400	invalid_request	`expires_at`	到期时刻不在未来或超过最长有效期	否	否	—	将 expires_at 设置为允许有效期内（默认 365 天）的未来 RFC 3339 时间戳，或使用 expires_in_secs。
400	invalid_request	`cu_cap`	cu_cap 上限越界（须为 1–9007199254740991 的整数）	否	否	—	调整 cu_cap 为 1–9007199254740991 之间的整数，或不填表示不设终身 CU 上限。
400	siwe_invalid	`expired`	以太坊登录（SIWE）消息已过期或 nonce 已被使用	否	是	立即获取新的 challenge 并在签名后提交	重新调用 /v1/auth/siwe/challenge 获取新的 challenge，签名新消息后再登录。
400	siwe_invalid	`chain_mismatch`	SIWE 消息中的 chainId 与服务端不匹配	否	否	—	在构造 SIWE 消息时使用 /v1/auth/siwe/challenge 返回的 chainId。
400	siwe_invalid	`domain_mismatch`	SIWE 消息中的 domain 与服务端主机名不匹配	否	否	—	确保 SIWE 消息中的 domain 与 uri 与 challenge 返回的主机名一致。
400	siwe_invalid	`signature`	SIWE 签名验证失败	否	否	—	核实签名是否由消息中指定的以太坊地址对应的私钥签署。
409	key_limit_reached	`active_keys`	未吊销且未过期的 API key 数量已达账户上限（包括已禁用的 key）	否	否	—	在创建新 key 之前，先在控制台或接口吊销一把闲置的 key。
409	no_reset_available	`nothing_to_reset`	当前余额已不低于重置目标；此次重置机会予以保留不消耗	否	否	—	当前无需重置；可在额度耗尽后再使用重置机会。
429	rate_limited	`daily_creations`	单账户 24 小时新建 API key 数量达到上限	否	是	遵循 Retry-After 响应头（秒）	遵循 Retry-After 等待创建配额恢复；轮换同样消耗该配额。
429	signup_rate_limited	`per_ip`	当前 IP 网段的新开户配额已用尽	否	是	遵循 Retry-After 响应头（秒）	遵循 Retry-After 响应头等待后再尝试开户。
429	signup_rate_limited	`global`	全局新用户开户频率已达上限	否	是	遵循 Retry-After 响应头（秒）	遵循 Retry-After 响应头等待后再尝试开户。
400	oauth_invalid	—	OAuth 授权参数错误，或回调的 state 未知、过期或已使用	否	是	—	重新从 /v1/auth/{provider}/start 发起授权流程。
400	login_code_invalid	—	Login code 未知、过期、已被使用，或 PKCE verifier 不匹配	否	否	—	重新发起登录以获取新的 login code。
401	unauthenticated	—	缺少会话凭证，或会话令牌无效、已过期或已被吊销；调用充值接口（/v1/topup/*）时，如果带了 Authorization 头但不是有效的控制台会话令牌，也会返回这个码	否	否	—	重新登录以获取新的 Bearer 会话令牌；调用充值接口时，改用 x-api-key 请求头传 API key。
403	user_disabled	—	账户已被停用	否	否	—	联系 contact@blockvectra.com 获取账户支持。
404	provider_disabled	—	该 OAuth 认证方式暂未开启	否	否	—	使用以太坊钱包登录（SIWE）或其他已启用的登录方式。
409	identity_in_use	—	该身份（钱包地址或 OAuth 账号）已被其他账户绑定	否	否	—	从旧账户解绑该身份，或使用其他身份进行绑定。
409	identity_limit_reached	—	该账户绑定的身份数量已达上限（5 个）	否	否	—	解绑不需要的旧身份后再绑定新身份。
409	last_identity	—	不能解绑账户唯一的身份	否	否	—	先绑定其他身份，然后才能解绑当前身份。
409	key_not_active	—	无法对已禁用、已吊销或已到期的 API key 进行轮换	否	否	—	创建新的 API key，或仅对处于 active 状态的 key 进行轮换。
409	no_reset_available	—	当前账户没有可用的额度重置机会	否	否	—	链上充值：在控制台或通过 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）获取充值地址，详见Agent 充值指南，或等待后续活动周期。
413	payload_too_large	—	请求体超过 64 KiB 大小上限	否	否	—	减小请求体体积，确保在 64 KiB 以内。
503	signup_paused	—	全局新用户注册暂时熔断暂停，已有用户可照常登录	否	是	稍后重试注册	新用户注册暂时维护；请稍后再试，已有账户登录不受影响。
503	usage_unavailable	—	用量统计服务暂时不可用（仅影响 /usage）	否	是	等待数秒后重试	仅影响 /usage 端点，其他接口正常可用；稍后重试查询用量即可。
500	internal	—	服务端发生未预期的内部错误	否	是	稍后重试	使用指数退避稍后重试。
400	invalid_address	`invalid_address`	收款地址格式或校验和无效	否	否	—	使用 0x 加 40 位十六进制字符，小写或符合 EIP-55 校验和；检查 data.field（/address）。
503	faucet_empty	`faucet_empty`	水龙头余额不足以支付本次领取金额和交易手续费	否	是	遵循 Retry-After 响应头（秒）	按 Retry-After 等待后重试；未收到受理响应时，不要假定测试 ETH 已发放。
503	service_unavailable	`service_unavailable`	水龙头领取处理暂不可用，或上一笔领取尚无回执	否	是	遵循 Retry-After 响应头（秒）	按 Retry-After 等待后重试；未收到受理响应时，不要假定测试 ETH 已发放。

推送 API 错误

Webhook 订阅管理与事件历史接口（/v1/push/）返回的错误。

HTTP	错误码	原因码	含义	是否计费	能否重试	等待时间（Retry-After）	Agent 建议动作
400	invalid_request	—	请求字段、地址、分页或区块区间无效。	否	否	—	检查 data.field 与 data.invalid，修正请求。
401	missing_api_key	—	缺少 x-api-key。	否	否	—	在 x-api-key 请求头中提供 API key。
401	invalid_api_key	—	API key 未知、已停用或已吊销。	否	否	—	使用本账户有效的 key。
402	insufficient_balance	—	事件历史查询余额或免费额度已耗尽。	否	否	—	查看 data.reason（balance_exhausted 或 free_grant_exhausted）及可用的 data.balance_units / data.balance_cu；通过 data.topup_url 或 data.deposit_address_url 充值。
403	key_cap_exhausted	—	事件历史查询所用 API key 的 CU 总额度已耗尽。	否	否	—	查看 data.cu_cap，在控制台创建新 key。
403	key_expired	—	API key 已过期。	否	否	—	使用本账户未过期的 key。
404	not_found	—	路由、方法或订阅不存在。	否	否	—	检查路径、方法与订阅所属账户。
409	limit_reached	—	账户订阅数或地址订阅对数达到上限。	否	否	—	查看 data.limit 与 data.max，减少订阅或地址。
413	request_too_large	—	请求体超过端点限制。	否	否	—	拆分地址批次或缩小请求体。
422	chain_not_available	—	链不可用于推送或未加入该订阅。	否	否	—	核对 GET /v1/push/chains 与订阅的 chains。
422	chains_required	—	至少需要指定一条链。	否	否	—	提供非空 chains 对象；停止监听时使用 offline 状态。
422	confirmations_out_of_range	—	确认数超出该链范围。	否	否	—	选择 data.min 到 data.max 范围内的 confirmations。
422	destination_not_allowed	—	接收 URL 不符合要求。	否	否	—	检查 data.rule，使用端口 443 的 HTTPS 主机名，不含用户信息或 fragment。
422	block_out_of_range	—	区块范围超出可重放或历史查询范围。	否	否	—	按 data.min_block 与 data.max_block 调整区块范围。
429	cost_exceeds_burst	—	历史查询费用超过 key 的突发容量。	否	否	—	查看 data.reason（request_exceeds_burst）与 data.max，提高突发容量后再试；原样重试无效。
429	rate_limited	—	管理接口或历史查询达到速率限制。	否	是	等待 Retry-After 指定的秒数。	历史查询查看 data.reason（key_rate_limit 或 free_plan_call_limit）；等待 Retry-After 指定秒数并降低请求频率或并发。
500	internal_error	—	服务发生异常。	否	否	—	保留 x-bv-request-id 并联系支持。
503	auth_unavailable	—	API key 校验暂不可用。	否	是	等待 Retry-After 指定的秒数。	等待 Retry-After 指定秒数后重试。
503	billing_unavailable	—	历史查询计费状态暂不可用。	否	是	等待 Retry-After 指定的秒数。	等待 Retry-After 指定秒数后重试。
503	upstream_unavailable	—	推送服务暂不可达。	否	是	等待 Retry-After 指定的秒数。	等待 Retry-After 指定秒数后重试。
503	service_unavailable	—	推送服务或地址容量暂不可用。	否	是	等待 Retry-After 指定的秒数。	等待 Retry-After 指定秒数后重试。

Webhook 订阅或重放错误参阅推送恢复指南。接收端先实现原始正文验签，稳定币收款示例提供事件去重、收款校验、缺口补扫与重组核对路径。计量方式见计费规则，连接型订阅的恢复见 WebSocket 重连。

遇到 logs_range_too_large 时，查看 eth_getLogs 方法参数，并按区块范围限制与分段查询指南缩小查询跨度。

Robinhood Chain 上的领取资格及共用错误码的处理方式，见测试网水龙头指南。

排查 eth_estimateGas 或 eth_call 的参数编码时，按 EIP-1474 的 value encoding 处理 Quantity 与 Data：大整数不要用 JavaScript Number 编码，不要 catch 后默认归零，先读取实际返回的 code、reason 及 HTTP status 再判断——invalid params 不应自动当作 slippage 或重试/退避条件。

错误参考

JSON-RPC 错误

WebSocket 关闭码

Data API 错误

控制台、账户与水龙头 API 错误

推送 API 错误