错误参考
BlockVectra JSON-RPC、Data API 与控制台接口的完整错误码、原因码（reason）、计费规则、重试策略与 Agent 建议动作参考。
本参考文档收录 BlockVectra 服务的完整错误码与机器可读原因码（reason），明确标示被拒绝调用的计费规则、重试策略、退避时间以及面向 AI Agent 与自动化客户端的建议处理动作。
如需机器读取，可通过 /errors.json 获取完整的 JSON 格式错误目录。错误响应中携带的 docs_url 直接链接到本页面的稳定锚点：https://docs.blockvectra.com/en/errors/#<reason>（无 reason 的错误使用错误码锚点，如 #<code-number>）。
特殊空响应体说明
HTTP 404（空响应体）：未带 key、key 无效、已停用或已吊销
向 /v1/{chain} 发起请求时若未携带 API key、或 key 未知、被停用或已吊销，服务端返回 HTTP 404 空响应体。出于安全防探测考量，服务端不区分 key 是否存在或具体停用状态。Agent 建议动作：确保在 x-api-key 请求头传入有效 key 或设置 BLOCKVECTRA_API_KEY 环境变量。
HTTP 403（空响应体）：JSON-RPC 端点使用了非 POST 方法
向 /v1/{chain} 或 /v1/{chain}/{api_key} 发起请求时若使用了 POST 与 OPTIONS 之外的方法（如 GET），服务端返回 HTTP 403 空响应体并带 Allow: POST,OPTIONS 响应头。Agent 建议动作：JSON-RPC 调用一律使用 POST 方法。
JSON-RPC 错误
JSON-RPC 分发、底层节点转发或准入控制层返回的错误。
| HTTP | 错误码 | 原因码 | 含义 | 是否计费 | 能否重试 | 等待时间（Retry-After） | Agent 建议动作 | 相关文档 | 锚点 |
|---|---|---|---|---|---|---|---|---|---|
| 200 | -32700 | parse_error | JSON 解析错误，请求体不是合法的 JSON 语法 | 否 | 否 | — | 核实请求体为合法的 JSON 语法后再发送。 | JSON-RPC 文档 | #parse_error |
| 200 | -32600 | invalid_request | JSON-RPC 请求格式不合法、成员名存在二义性或不是合法的对象/数组 | 否 | 否 | — | 检查请求体结构；修正 jsonrpc: '2.0'、id 与 method 字段后再发送。 | JSON-RPC 文档 | #invalid_request |
| 200 | -32600 | batch_too_large | 批量请求包含的调用数超过单批上限 | 否 | 否 | — | 将批量请求拆分为更小的批次，使单批调用数在上限以内。 | JSON-RPC 文档 | #batch_too_large |
| 200 | -32601 | method_not_allowed | 方法在该链上不可用或已被策略禁用 | 否 | 否 | — | 通过 GET /v1/chains 查询该链的 methods.allow 与 methods.deny 策略确认支持的方法。 | JSON-RPC 文档 | #method_not_allowed |
| 404 | -32600 | unknown_chain | 请求的链标识不存在或不受支持 | 否 | 否 | — | 通过 GET /v1/chains 或 list_chains 工具获取受支持的链列表，核对 URL 路径中的链名。 | JSON-RPC 文档 | #unknown_chain |
| 200 | -32602 | logs_range_too_large | eth_getLogs 查询的区块跨度超过该链允许的上限 | 否 | 否 | — | 缩窄日志查询的区块范围至 GET /v1/chains 中的 max_logs_block_range 上限以内。 | JSON-RPC 文档 | #logs_range_too_large |
| 200 | -32602 | invalid_params | 方法参数不合法（如不支持的 tracer 或超时时间超限） | 否 | 否 | — | 调整方法参数；核对该链支持的 tracer 列表与超时限制。 | JSON-RPC 文档 | #invalid_params |
| 200 | -32010 | node_syncing | 底层链节点正在同步中，调用暂时不可用 | 否 | 是 | 等待数秒后重试 | 等待节点同步完成，或查询 GET /v1/status 查看状态。 | JSON-RPC 文档 | #node_syncing |
| 200 | -32011 | state_window | 历史状态超出节点保留的最长区块窗口 | 否 | 否 | — | 仅查询 GET /v1/chains 中 state_window_blocks 范围内的区块，或改用 Data API 查询历史数据。 | JSON-RPC 文档 | #state_window |
| 200 | -32000 | not_found | 请求的交易、区块或资源不存在 | 否 | 是 | 若刚广播或刚出块，等待数秒后重试 | 若为刚广播的交易或最新出块，等待链同步后重试；否则核对区块号或哈希值。 | JSON-RPC 文档 | #not_found |
| 200 | -32000 | response_too_large | 底层节点返回的响应体超过服务端大小上限 | 否 | 否 | — | 缩窄查询范围（如缩小 eth_getLogs 区块区间或减少 trace 请求范围）。 | JSON-RPC 文档 | #response_too_large |
| 200 | -32005 | overloaded | 服务暂时过载 | 否 | 是 | 等待数秒并使用指数退避重试 | 结合抖动进行退避后重试请求。 | JSON-RPC 文档 | #overloaded |
| 429 | -32005 | key_rate_limit | API key 的计算单元（CU）速率上限超限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 休眠 Retry-After 指定的秒数后重试，或平摊请求流量。 | JSON-RPC 文档 | #key_rate_limit |
| 429 | -32005 | free_plan_call_limit | 免费套餐每秒调用次数上限超限 | 否 | 是 | 等待 1 秒后重试 | 降低请求发送频率，或联系充值升级为付费账户解锁更高吞吐量。 | JSON-RPC 文档 | #free_plan_call_limit |
| 429 | -32005 | concurrency_limit | 在途并发请求数超过上限 | 否 | 是 | 遵循 Retry-After 响应头或等待当前调用完成 | 限制客户端并发池大小，等待已有请求完成。 | JSON-RPC 文档 | #concurrency_limit |
| 429 | -32022 | request_exceeds_burst | 单次请求的 CU 权重超过单 key 突发上限容量 | 否 | 否 | — | 无需等待（等待不会成功）；须拆解批量请求或降低方法参数以适应突发容量。 | JSON-RPC 文档 | #request_exceeds_burst |
| 429 | -32022 | free_plan_batch_too_large | 单批调用数超过免费套餐每秒调用次数限制 | 否 | 否 | — | 无需等待；须将单批请求调用数拆小至免费套餐限额以内，或联系充值。 | JSON-RPC 文档 | #free_plan_batch_too_large |
| 200 | -32603 | upstream_unavailable | 底层链节点暂不可用、应答超时或返回畸形响应 | 否 | 是 | 等待数秒后重试 | 退避重试；可通过 GET /v1/status 查看节点健康度。 | JSON-RPC 文档 | #upstream_unavailable |
| 200 | -32603 | internal_error | 处理请求时发生内部错误 | 否 | 是 | 稍后重试 | 稍后重试；若持续失败请记录时间并联系支持团队。 | JSON-RPC 文档 | #internal_error |
| 402 | -32020 | balance_exhausted | 账户余额已耗尽 | 否 | 否 | — | 联系 contact@blockvectra.com 充值，或在控制台使用额度重置机会（如符合条件）。 | JSON-RPC 文档 | #balance_exhausted |
| 402 | -32020 | free_grant_exhausted | 免费套餐周期额度已耗尽 | 否 | 否 | — | 联系 contact@blockvectra.com 充值、在控制台使用额度重置机会，或等待下一个周期补足额度。 | JSON-RPC 文档 | #free_grant_exhausted |
| 401 | -32024 | missing_api_key | 请求缺少 API key，未在请求路径或请求头中提供 | 否 | 否 | — | 在请求路径（/v1/{chain}/<api_key>）或 x-api-key 请求头中传入有效的 API key。 | JSON-RPC 文档 | #missing_api_key |
| 503 | -32021 | billing_unavailable | 计费状态暂不可确认（新创建 key 正在同步或服务暂时繁忙） | 否 | 是 | 遵循 Retry-After 响应头（秒） | 非余额问题，新创建的 key 通常数秒内完成同步；按 Retry-After 等待后重试即可。 | JSON-RPC 文档 | #billing_unavailable |
| 200 | 4444 | — | 请求的区块已被底层节点裁剪 | 否 | 否 | — | 目标区块已超出节点的裁剪保留期，可改用 Data API 获取历史区块信息。 | JSON-RPC 文档 | #4444 |
| 200 | -32000 | — | 底层节点历史状态不存在或数据已被裁剪 | 否 | 否 | — | 缩窄查询到状态窗口以内，或改用 Data API 查询历史数据。 | JSON-RPC 文档 | #-32000 |
| 200 | -32002 | — | 底层节点批量执行超时 | 否 | 是 | 等待数秒后使用较小的批次重试 | 减少单批调用数量后重试。 | JSON-RPC 文档 | #-32002 |
| 200 | -32003 | — | 底层节点批处理响应体过大 | 否 | 否 | — | 拆分批次以减小单个响应体大小。 | JSON-RPC 文档 | #-32003 |
| 200 | -32600 | — | 批量请求被底层节点整体放弃拒绝 | 否 | 否 | — | 检查批次中各调用的参数规范；拆分后重试。 | JSON-RPC 文档 | #-32600 |
| 200 | * | — | 底层节点执行层返回的业务错误（如合约执行回滚 execution reverted、节点参数校验拒绝） | 是 | 否 | — | 节点已执行计算并按方法权重计费。检查回滚原因或调用参数，切勿盲目原样重试。 | JSON-RPC 文档 | #* |
| 408 | 408 | — | 从收完请求头到返回响应超过 35 秒超时，返回空响应体 | 可能 | 是 | 读请求等待数秒后重试 | 已转发给节点的调用在节点应答后照常计费。读请求可退避重试；写请求（如 eth_sendRawTransaction）须先按交易哈希查状态，切勿盲目重发。 | JSON-RPC 文档 | #408 |
Data API 错误
区块链 Data API 端点（/v1/data/{chain}/）返回的结构化错误。
| HTTP | 错误码 | 原因码 | 含义 | 是否计费 | 能否重试 | 等待时间（Retry-After） | Agent 建议动作 | 相关文档 | 锚点 |
|---|---|---|---|---|---|---|---|---|---|
| 400 | bad_request | — | 查询参数重复、查询字符串格式非法或请求格式错误 | 否 | 否 | — | 检查查询参数；确保 limit 等参数只出现一次，并核对参数格式。 | Data API 文档 | #bad_request |
| 409 | not_indexed_yet | — | 请求的区块高度超过当前已处理的高度（响应中携带 indexed_through 水位） | 否 | 是 | 等待数秒至 indexed_through 高度到达目标区块 | 等待数据处理进度赶上该区块高度后重试。 | Data API 文档 | #not_indexed_yet |
| 409 | finality_exceeded | — | 区块已收录但超过 finalized_block 最终确认高度（尚未达到重组安全条件） | 否 | 是 | 等待链最终确认推进 | 等待区块达到最终确认，或将查询范围限制在 meta.finalized_block 确认高度以内。 | Data API 文档 | #finality_exceeded |
| 409 | window_too_large | — | 区块窗口跨度超过 100,000 块且未设置 clamp=true | 否 | 否 | — | 缩窄区块区间至 100,000 块以内，或在查询参数中传入 clamp=true。 | Data API 文档 | #window_too_large |
| 409 | too_many_pools | — | 该代币命中的流动性池超过 200 个，须改按池维度查询 | 否 | 否 | — | 按具体的流动性池地址查询，而非按代币维度全量匹配。 | Data API 文档 | #too_many_pools |
| 409 | span_exceeded | — | 请求的时间跨度超过 90 天上限 | 否 | 否 | — | 将 from_time 与 to_time 的时间跨度缩窄至 90 天以内。 | Data API 文档 | #span_exceeded |
| 422 | no_coverage | — | 该链不支持该特性，或请求的区块早于历史覆盖起点 | 否 | 否 | — | 查询前核实 GET /v1/data/{chain}/status 中的功能支持与 coverage.from_block 起点。 | Data API 文档 | #no_coverage |
| 503 | unavailable | — | 数据服务暂时不可用、查询槽位已满或正在维护 | 否 | 是 | 等待数秒并使用指数退避重试 | 使用指数退避稍后重试。 | Data API 文档 | #unavailable |
控制台与账户 API 错误
管理端点与认证接口返回的错误。
| HTTP | 错误码 | 原因码 | 含义 | 是否计费 | 能否重试 | 等待时间（Retry-After） | Agent 建议动作 | 相关文档 | 锚点 |
|---|---|---|---|---|---|---|---|---|---|
| 400 | invalid_request | invalid_username | 用户名格式不合法（须为英文字母、数字或下划线） | 否 | 否 | — | 提供符合字符与长度规范的有效用户名。 | — | #invalid_username |
| 400 | siwe_invalid | expired | 以太坊登录（SIWE）消息已过期或 nonce 已被使用 | 否 | 是 | 立即获取新的 challenge 并在签名后提交 | 重新调用 /v1/auth/siwe/challenge 获取新的 challenge，签名新消息后再登录。 | — | #expired |
| 400 | siwe_invalid | chain_mismatch | SIWE 消息中的 chainId 与服务端不匹配 | 否 | 否 | — | 在构造 SIWE 消息时使用 /v1/auth/siwe/challenge 返回的 chainId。 | — | #chain_mismatch |
| 400 | siwe_invalid | domain_mismatch | SIWE 消息中的 domain 与服务端主机名不匹配 | 否 | 否 | — | 确保 SIWE 消息中的 domain 与 uri 与 challenge 返回的主机名一致。 | — | #domain_mismatch |
| 400 | siwe_invalid | signature | SIWE 签名验证失败 | 否 | 否 | — | 核实签名是否由消息中指定的以太坊地址对应的私钥签署。 | — | #signature |
| 409 | key_limit_reached | active_keys | 未吊销的有效 API key 数量已达账户上限 | 否 | 否 | — | 在创建新 key 之前，先在控制台或接口吊销一把闲置的 key。 | — | #active_keys |
| 409 | no_reset_available | nothing_to_reset | 当前余额已不低于重置目标；此次重置机会予以保留不消耗 | 否 | 否 | — | 当前无需重置；可在额度耗尽后再使用重置机会。 | — | #nothing_to_reset |
| 429 | rate_limited | daily_creations | 单账户 24 小时新建 API key 数量达到上限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 对现有 key 进行轮换而非新建，或按 Retry-After 建议等待 24 小时窗口刷新。 | — | #daily_creations |
| 429 | signup_rate_limited | per_ip | 当前 IP 网段的新开户配额已用尽 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 遵循 Retry-After 响应头等待后再尝试开户。 | — | #per_ip |
| 429 | signup_rate_limited | global | 全局新用户开户频率已达上限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 遵循 Retry-After 响应头等待后再尝试开户。 | — | #global |
| 400 | oauth_invalid | — | OAuth 授权参数错误，或回调的 state 未知、过期或已使用 | 否 | 是 | — | 重新从 /v1/auth/oauth/{provider}/start 发起授权流程。 | — | #oauth_invalid |
| 400 | login_code_invalid | — | Login code 未知、过期、已被使用，或 PKCE verifier 不匹配 | 否 | 否 | — | 重新发起登录以获取新的 login code。 | — | #login_code_invalid |
| 401 | unauthenticated | — | 缺少会话凭证，或会话令牌无效、已过期或已被吊销 | 否 | 否 | — | 重新登录以获取新的 Bearer 会话令牌。 | — | #unauthenticated |
| 403 | user_disabled | — | 账户已被停用 | 否 | 否 | — | 联系 contact@blockvectra.com 获取账户支持。 | — | #user_disabled |
| 404 | provider_disabled | — | 该 OAuth 认证方式暂未开启 | 否 | 否 | — | 使用以太坊钱包登录（SIWE）或其他已启用的登录方式。 | — | #provider_disabled |
| 409 | identity_in_use | — | 该身份（钱包地址或 OAuth 账号）已被其他账户绑定 | 否 | 否 | — | 从旧账户解绑该身份，或使用其他身份进行绑定。 | — | #identity_in_use |
| 409 | identity_limit_reached | — | 该账户绑定的身份数量已达上限（5 个） | 否 | 否 | — | 解绑不需要的旧身份后再绑定新身份。 | — | #identity_limit_reached |
| 409 | last_identity | — | 不能解绑账户唯一的身份 | 否 | 否 | — | 先绑定其他身份，然后才能解绑当前身份。 | — | #last_identity |
| 409 | key_not_active | — | 无法对已禁用或已吊销的 API key 进行轮换 | 否 | 否 | — | 创建新的 API key，或仅对处于 active 状态的 key 进行轮换。 | — | #key_not_active |
| 409 | no_reset_available | — | 当前账户没有可用的额度重置机会 | 否 | 否 | — | 联系 contact@blockvectra.com 充值，或等待后续活动周期。 | — | #no_reset_available |
| 413 | payload_too_large | — | 请求体超过 64 KiB 大小上限 | 否 | 否 | — | 减小请求体体积，确保在 64 KiB 以内。 | — | #payload_too_large |
| 429 | rate_limited | — | 控制面接口请求频率超限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 休眠 Retry-After 指定的秒数后重试。 | — | #rate_limited |
| 429 | signup_rate_limited | — | 当前 IP 网段的新开户配额已用尽 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 等待 Retry-After 间隔后重试开户。 | — | #signup_rate_limited |
| 503 | signup_paused | — | 全局新用户注册暂时熔断暂停，已有用户可照常登录 | 否 | 是 | 稍后重试注册 | 新用户注册暂时维护；请稍后再试，已有账户登录不受影响。 | — | #signup_paused |
| 503 | usage_unavailable | — | 用量统计服务暂时不可用（仅影响 /usage） | 否 | 是 | 等待数秒后重试 | 仅影响 /usage 端点，其他接口正常可用；稍后重试查询用量即可。 | — | #usage_unavailable |
| 500 | internal | — | 服务端发生未预期的内部错误 | 否 | 是 | 稍后重试 | 使用指数退避稍后重试。 | — | #internal |
最后更新：