# 错误参考

> 原文地址: https://docs.blockvectra.com/zh/errors/

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

如需机器读取，可通过 [/errors.json](https://docs.blockvectra.com/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 语法后再发送。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#parse_error](https://docs.blockvectra.com/en/errors/#parse_error) |
| 200 | -32600 | `invalid_request` | JSON-RPC 请求格式不合法、成员名存在二义性或不是合法的对象/数组 | 否 | 否 | — | 检查请求体结构；修正 jsonrpc: '2.0'、id 与 method 字段后再发送。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#invalid_request](https://docs.blockvectra.com/en/errors/#invalid_request) |
| 200 | -32600 | `batch_too_large` | 批量请求包含的调用数超过单批上限 | 否 | 否 | — | 将批量请求拆分为更小的批次，使单批调用数在上限以内。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#batch_too_large](https://docs.blockvectra.com/en/errors/#batch_too_large) |
| 200 | -32601 | `method_not_allowed` | 方法在该链上不可用或已被策略禁用 | 否 | 否 | — | 通过 GET /v1/chains 查询该链的 methods.allow 与 methods.deny 策略确认支持的方法。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#method_not_allowed](https://docs.blockvectra.com/en/errors/#method_not_allowed) |
| 404 | -32600 | `unknown_chain` | 请求的链标识不存在或不受支持 | 否 | 否 | — | 通过 GET /v1/chains 或 list_chains 工具获取受支持的链列表，核对 URL 路径中的链名。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#unknown_chain](https://docs.blockvectra.com/en/errors/#unknown_chain) |
| 200 | -32602 | `logs_range_too_large` | eth_getLogs 查询的区块跨度超过该链允许的上限 | 否 | 否 | — | 缩窄日志查询的区块范围至 GET /v1/chains 中的 max_logs_block_range 上限以内。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#logs_range_too_large](https://docs.blockvectra.com/en/errors/#logs_range_too_large) |
| 200 | -32602 | `invalid_params` | 方法参数不合法（如不支持的 tracer 或超时时间超限） | 否 | 否 | — | 调整方法参数；核对该链支持的 tracer 列表与超时限制。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#invalid_params](https://docs.blockvectra.com/en/errors/#invalid_params) |
| 200 | -32010 | `node_syncing` | 底层链节点正在同步中，调用暂时不可用 | 否 | 是 | 等待数秒后重试 | 等待节点同步完成，或查询 GET /v1/status 查看状态。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#node_syncing](https://docs.blockvectra.com/en/errors/#node_syncing) |
| 200 | -32011 | `state_window` | 历史状态超出节点保留的最长区块窗口 | 否 | 否 | — | 仅查询 GET /v1/chains 中 state_window_blocks 范围内的区块，或改用 Data API 查询历史数据。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#state_window](https://docs.blockvectra.com/en/errors/#state_window) |
| 200 | -32000 | `not_found` | 请求的交易、区块或资源不存在 | 否 | 是 | 若刚广播或刚出块，等待数秒后重试 | 若为刚广播的交易或最新出块，等待链同步后重试；否则核对区块号或哈希值。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#not_found](https://docs.blockvectra.com/en/errors/#not_found) |
| 200 | -32000 | `response_too_large` | 底层节点返回的响应体超过服务端大小上限 | 否 | 否 | — | 缩窄查询范围（如缩小 eth_getLogs 区块区间或减少 trace 请求范围）。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#response_too_large](https://docs.blockvectra.com/en/errors/#response_too_large) |
| 200 | -32005 | `overloaded` | 服务暂时过载 | 否 | 是 | 等待数秒并使用指数退避重试 | 结合抖动进行退避后重试请求。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#overloaded](https://docs.blockvectra.com/en/errors/#overloaded) |
| 429 | -32005 | `key_rate_limit` | API key 的计算单元（CU）速率上限超限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 休眠 Retry-After 指定的秒数后重试，或平摊请求流量。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#key_rate_limit](https://docs.blockvectra.com/en/errors/#key_rate_limit) |
| 429 | -32005 | `free_plan_call_limit` | 免费套餐每秒调用次数上限超限 | 否 | 是 | 等待 1 秒后重试 | 降低请求发送频率，或联系充值升级为付费账户解锁更高吞吐量。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#free_plan_call_limit](https://docs.blockvectra.com/en/errors/#free_plan_call_limit) |
| 429 | -32005 | `concurrency_limit` | 在途并发请求数超过上限 | 否 | 是 | 遵循 Retry-After 响应头或等待当前调用完成 | 限制客户端并发池大小，等待已有请求完成。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#concurrency_limit](https://docs.blockvectra.com/en/errors/#concurrency_limit) |
| 429 | -32022 | `request_exceeds_burst` | 单次请求的 CU 权重超过单 key 突发上限容量 | 否 | 否 | — | 无需等待（等待不会成功）；须拆解批量请求或降低方法参数以适应突发容量。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#request_exceeds_burst](https://docs.blockvectra.com/en/errors/#request_exceeds_burst) |
| 429 | -32022 | `free_plan_batch_too_large` | 单批调用数超过免费套餐每秒调用次数限制 | 否 | 否 | — | 无需等待；须将单批请求调用数拆小至免费套餐限额以内，或联系充值。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#free_plan_batch_too_large](https://docs.blockvectra.com/en/errors/#free_plan_batch_too_large) |
| 200 | -32603 | `upstream_unavailable` | 底层链节点暂不可用、应答超时或返回畸形响应 | 否 | 是 | 等待数秒后重试 | 退避重试；可通过 GET /v1/status 查看节点健康度。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#upstream_unavailable](https://docs.blockvectra.com/en/errors/#upstream_unavailable) |
| 200 | -32603 | `internal_error` | 处理请求时发生内部错误 | 否 | 是 | 稍后重试 | 稍后重试；若持续失败请记录时间并联系支持团队。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#internal_error](https://docs.blockvectra.com/en/errors/#internal_error) |
| 402 | -32020 | `balance_exhausted` | 账户余额已耗尽 | 否 | 否 | — | 联系 contact@blockvectra.com 充值，或在控制台使用额度重置机会（如符合条件）。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#balance_exhausted](https://docs.blockvectra.com/en/errors/#balance_exhausted) |
| 402 | -32020 | `free_grant_exhausted` | 免费套餐周期额度已耗尽 | 否 | 否 | — | 联系 contact@blockvectra.com 充值、在控制台使用额度重置机会，或等待下一个周期补足额度。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#free_grant_exhausted](https://docs.blockvectra.com/en/errors/#free_grant_exhausted) |
| 401 | -32024 | `missing_api_key` | 请求缺少 API key，未在请求路径或请求头中提供 | 否 | 否 | — | 在请求路径（/v1/{chain}/<api_key>）或 x-api-key 请求头中传入有效的 API key。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#missing_api_key](https://docs.blockvectra.com/en/errors/#missing_api_key) |
| 503 | -32021 | `billing_unavailable` | 计费状态暂不可确认（新创建 key 正在同步或服务暂时繁忙） | 否 | 是 | 遵循 Retry-After 响应头（秒） | 非余额问题，新创建的 key 通常数秒内完成同步；按 Retry-After 等待后重试即可。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#billing_unavailable](https://docs.blockvectra.com/en/errors/#billing_unavailable) |
| 200 | 4444 | — | 请求的区块已被底层节点裁剪 | 否 | 否 | — | 目标区块已超出节点的裁剪保留期，可改用 Data API 获取历史区块信息。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#4444](https://docs.blockvectra.com/en/errors/#4444) |
| 200 | -32000 | — | 底层节点历史状态不存在或数据已被裁剪 | 否 | 否 | — | 缩窄查询到状态窗口以内，或改用 Data API 查询历史数据。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#-32000](https://docs.blockvectra.com/en/errors/#-32000) |
| 200 | -32002 | — | 底层节点批量执行超时 | 否 | 是 | 等待数秒后使用较小的批次重试 | 减少单批调用数量后重试。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#-32002](https://docs.blockvectra.com/en/errors/#-32002) |
| 200 | -32003 | — | 底层节点批处理响应体过大 | 否 | 否 | — | 拆分批次以减小单个响应体大小。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#-32003](https://docs.blockvectra.com/en/errors/#-32003) |
| 200 | -32600 | — | 批量请求被底层节点整体放弃拒绝 | 否 | 否 | — | 检查批次中各调用的参数规范；拆分后重试。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#-32600](https://docs.blockvectra.com/en/errors/#-32600) |
| 200 | * | — | 底层节点执行层返回的业务错误（如合约执行回滚 execution reverted、节点参数校验拒绝） | 是 | 否 | — | 节点已执行计算并按方法权重计费。检查回滚原因或调用参数，切勿盲目原样重试。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#*](https://docs.blockvectra.com/en/errors/#*) |
| 408 | 408 | — | 从收完请求头到返回响应超过 35 秒超时，返回空响应体 | 可能 | 是 | 读请求等待数秒后重试 | 已转发给节点的调用在节点应答后照常计费。读请求可退避重试；写请求（如 eth_sendRawTransaction）须先按交易哈希查状态，切勿盲目重发。 | [相关文档](https://docs.blockvectra.com/zh/api/json-rpc/) | [#408](https://docs.blockvectra.com/en/errors/#408) |

### Data API 错误

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

| HTTP | 错误码 | 原因码 | 含义 | 是否计费 | 能否重试 | 等待时间（Retry-After） | Agent 建议动作 | 相关文档 | 锚点 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | 查询参数重复、查询字符串格式非法或请求格式错误 | 否 | 否 | — | 检查查询参数；确保 limit 等参数只出现一次，并核对参数格式。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#bad_request](https://docs.blockvectra.com/en/errors/#bad_request) |
| 409 | not_indexed_yet | — | 请求的区块高度超过当前已处理的高度（响应中携带 indexed_through 水位） | 否 | 是 | 等待数秒至 indexed_through 高度到达目标区块 | 等待数据处理进度赶上该区块高度后重试。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#not_indexed_yet](https://docs.blockvectra.com/en/errors/#not_indexed_yet) |
| 409 | finality_exceeded | — | 区块已收录但超过 finalized_block 最终确认高度（尚未达到重组安全条件） | 否 | 是 | 等待链最终确认推进 | 等待区块达到最终确认，或将查询范围限制在 meta.finalized_block 确认高度以内。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#finality_exceeded](https://docs.blockvectra.com/en/errors/#finality_exceeded) |
| 409 | window_too_large | — | 区块窗口跨度超过 100,000 块且未设置 clamp=true | 否 | 否 | — | 缩窄区块区间至 100,000 块以内，或在查询参数中传入 clamp=true。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#window_too_large](https://docs.blockvectra.com/en/errors/#window_too_large) |
| 409 | too_many_pools | — | 该代币命中的流动性池超过 200 个，须改按池维度查询 | 否 | 否 | — | 按具体的流动性池地址查询，而非按代币维度全量匹配。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#too_many_pools](https://docs.blockvectra.com/en/errors/#too_many_pools) |
| 409 | span_exceeded | — | 请求的时间跨度超过 90 天上限 | 否 | 否 | — | 将 from_time 与 to_time 的时间跨度缩窄至 90 天以内。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#span_exceeded](https://docs.blockvectra.com/en/errors/#span_exceeded) |
| 422 | no_coverage | — | 该链不支持该特性，或请求的区块早于历史覆盖起点 | 否 | 否 | — | 查询前核实 GET /v1/data/{chain}/status 中的功能支持与 coverage.from_block 起点。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#no_coverage](https://docs.blockvectra.com/en/errors/#no_coverage) |
| 503 | unavailable | — | 数据服务暂时不可用、查询槽位已满或正在维护 | 否 | 是 | 等待数秒并使用指数退避重试 | 使用指数退避稍后重试。 | [相关文档](https://docs.blockvectra.com/zh/api/data/) | [#unavailable](https://docs.blockvectra.com/en/errors/#unavailable) |

### 控制台与账户 API 错误

管理端点与认证接口返回的错误。

| HTTP | 错误码 | 原因码 | 含义 | 是否计费 | 能否重试 | 等待时间（Retry-After） | Agent 建议动作 | 相关文档 | 锚点 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | `invalid_username` | 用户名格式不合法（须为英文字母、数字或下划线） | 否 | 否 | — | 提供符合字符与长度规范的有效用户名。 | — | [#invalid_username](https://docs.blockvectra.com/en/errors/#invalid_username) |
| 400 | siwe_invalid | `expired` | 以太坊登录（SIWE）消息已过期或 nonce 已被使用 | 否 | 是 | 立即获取新的 challenge 并在签名后提交 | 重新调用 /v1/auth/siwe/challenge 获取新的 challenge，签名新消息后再登录。 | — | [#expired](https://docs.blockvectra.com/en/errors/#expired) |
| 400 | siwe_invalid | `chain_mismatch` | SIWE 消息中的 chainId 与服务端不匹配 | 否 | 否 | — | 在构造 SIWE 消息时使用 /v1/auth/siwe/challenge 返回的 chainId。 | — | [#chain_mismatch](https://docs.blockvectra.com/en/errors/#chain_mismatch) |
| 400 | siwe_invalid | `domain_mismatch` | SIWE 消息中的 domain 与服务端主机名不匹配 | 否 | 否 | — | 确保 SIWE 消息中的 domain 与 uri 与 challenge 返回的主机名一致。 | — | [#domain_mismatch](https://docs.blockvectra.com/en/errors/#domain_mismatch) |
| 400 | siwe_invalid | `signature` | SIWE 签名验证失败 | 否 | 否 | — | 核实签名是否由消息中指定的以太坊地址对应的私钥签署。 | — | [#signature](https://docs.blockvectra.com/en/errors/#signature) |
| 409 | key_limit_reached | `active_keys` | 未吊销的有效 API key 数量已达账户上限 | 否 | 否 | — | 在创建新 key 之前，先在控制台或接口吊销一把闲置的 key。 | — | [#active_keys](https://docs.blockvectra.com/en/errors/#active_keys) |
| 409 | no_reset_available | `nothing_to_reset` | 当前余额已不低于重置目标；此次重置机会予以保留不消耗 | 否 | 否 | — | 当前无需重置；可在额度耗尽后再使用重置机会。 | — | [#nothing_to_reset](https://docs.blockvectra.com/en/errors/#nothing_to_reset) |
| 429 | rate_limited | `daily_creations` | 单账户 24 小时新建 API key 数量达到上限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 对现有 key 进行轮换而非新建，或按 Retry-After 建议等待 24 小时窗口刷新。 | — | [#daily_creations](https://docs.blockvectra.com/en/errors/#daily_creations) |
| 429 | signup_rate_limited | `per_ip` | 当前 IP 网段的新开户配额已用尽 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 遵循 Retry-After 响应头等待后再尝试开户。 | — | [#per_ip](https://docs.blockvectra.com/en/errors/#per_ip) |
| 429 | signup_rate_limited | `global` | 全局新用户开户频率已达上限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 遵循 Retry-After 响应头等待后再尝试开户。 | — | [#global](https://docs.blockvectra.com/en/errors/#global) |
| 400 | oauth_invalid | — | OAuth 授权参数错误，或回调的 state 未知、过期或已使用 | 否 | 是 | — | 重新从 /v1/auth/oauth/{provider}/start 发起授权流程。 | — | [#oauth_invalid](https://docs.blockvectra.com/en/errors/#oauth_invalid) |
| 400 | login_code_invalid | — | Login code 未知、过期、已被使用，或 PKCE verifier 不匹配 | 否 | 否 | — | 重新发起登录以获取新的 login code。 | — | [#login_code_invalid](https://docs.blockvectra.com/en/errors/#login_code_invalid) |
| 401 | unauthenticated | — | 缺少会话凭证，或会话令牌无效、已过期或已被吊销 | 否 | 否 | — | 重新登录以获取新的 Bearer 会话令牌。 | — | [#unauthenticated](https://docs.blockvectra.com/en/errors/#unauthenticated) |
| 403 | user_disabled | — | 账户已被停用 | 否 | 否 | — | 联系 contact@blockvectra.com 获取账户支持。 | — | [#user_disabled](https://docs.blockvectra.com/en/errors/#user_disabled) |
| 404 | provider_disabled | — | 该 OAuth 认证方式暂未开启 | 否 | 否 | — | 使用以太坊钱包登录（SIWE）或其他已启用的登录方式。 | — | [#provider_disabled](https://docs.blockvectra.com/en/errors/#provider_disabled) |
| 409 | identity_in_use | — | 该身份（钱包地址或 OAuth 账号）已被其他账户绑定 | 否 | 否 | — | 从旧账户解绑该身份，或使用其他身份进行绑定。 | — | [#identity_in_use](https://docs.blockvectra.com/en/errors/#identity_in_use) |
| 409 | identity_limit_reached | — | 该账户绑定的身份数量已达上限（5 个） | 否 | 否 | — | 解绑不需要的旧身份后再绑定新身份。 | — | [#identity_limit_reached](https://docs.blockvectra.com/en/errors/#identity_limit_reached) |
| 409 | last_identity | — | 不能解绑账户唯一的身份 | 否 | 否 | — | 先绑定其他身份，然后才能解绑当前身份。 | — | [#last_identity](https://docs.blockvectra.com/en/errors/#last_identity) |
| 409 | key_not_active | — | 无法对已禁用或已吊销的 API key 进行轮换 | 否 | 否 | — | 创建新的 API key，或仅对处于 active 状态的 key 进行轮换。 | — | [#key_not_active](https://docs.blockvectra.com/en/errors/#key_not_active) |
| 409 | no_reset_available | — | 当前账户没有可用的额度重置机会 | 否 | 否 | — | 联系 contact@blockvectra.com 充值，或等待后续活动周期。 | — | [#no_reset_available](https://docs.blockvectra.com/en/errors/#no_reset_available) |
| 413 | payload_too_large | — | 请求体超过 64 KiB 大小上限 | 否 | 否 | — | 减小请求体体积，确保在 64 KiB 以内。 | — | [#payload_too_large](https://docs.blockvectra.com/en/errors/#payload_too_large) |
| 429 | rate_limited | — | 控制面接口请求频率超限 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 休眠 Retry-After 指定的秒数后重试。 | — | [#rate_limited](https://docs.blockvectra.com/en/errors/#rate_limited) |
| 429 | signup_rate_limited | — | 当前 IP 网段的新开户配额已用尽 | 否 | 是 | 遵循 Retry-After 响应头（秒） | 等待 Retry-After 间隔后重试开户。 | — | [#signup_rate_limited](https://docs.blockvectra.com/en/errors/#signup_rate_limited) |
| 503 | signup_paused | — | 全局新用户注册暂时熔断暂停，已有用户可照常登录 | 否 | 是 | 稍后重试注册 | 新用户注册暂时维护；请稍后再试，已有账户登录不受影响。 | — | [#signup_paused](https://docs.blockvectra.com/en/errors/#signup_paused) |
| 503 | usage_unavailable | — | 用量统计服务暂时不可用（仅影响 /usage） | 否 | 是 | 等待数秒后重试 | 仅影响 /usage 端点，其他接口正常可用；稍后重试查询用量即可。 | — | [#usage_unavailable](https://docs.blockvectra.com/en/errors/#usage_unavailable) |
| 500 | internal | — | 服务端发生未预期的内部错误 | 否 | 是 | 稍后重试 | 使用指数退避稍后重试。 | — | [#internal](https://docs.blockvectra.com/en/errors/#internal) |