指南
哪些请求不计费：错误码与计费规则
详细梳理 HTTP 状态码、JSON-RPC 错误码与 Data API 中的计费判定规则与开发者建议操作。
BlockVectra 服务按计算单元（CU，Compute Unit）计量。调用仅在得到应答后计费，不会在请求到达时预扣。本文汇总 HTTP 状态码、JSON-RPC 接口以及 Data API 在不同响应和错误场景下的计费判定规则，并列出推荐的开发者处理方式。
HTTP 状态码与计费判定
HTTP 层的请求拦截与处理结果计费规则如下：
| HTTP 状态码 | 响应内容 | 场景说明 | 是否计费 | 开发者建议操作 |
|---|---|---|---|---|
| 200 | JSON-RPC 响应（单个或数组） | 正常应答；所有 JSON-RPC 层错误（解析错误、方法拒绝、守卫、上游失败、节点错误）也是 200 | 按调用判定 | 检查各调用的 result 或 error；若返回错误，参见下文 JSON-RPC 错误码处理方式 |
| 204 | 空 | 请求中全部调用都是 notification | notification 照常计费 | notification 已受理并在后台处理，无需额外操作 |
| 400 | 空 | HTTP 报文畸形（请求行或请求头无法解析、非法 chunked 编码）、请求体两次读之间超过 10 s | 否 | 检查 HTTP 请求格式、请求头与传输连贯性 |
| 402 | JSON，-32020 | 余额不足、额度耗尽（刚创建的 key 在系统读到包含其账户的计费数据之前不会返回 402，见 503） | 否 | 前往控制台账单页查看余额与充值 |
| 403 | 空 | /v1/{chain}、/v1/{chain}/{api_key} 上除 POST、OPTIONS 外的方法（链名已知或未知都一样） | 否 | 将 HTTP 请求方法改为 POST（或跨域 OPTIONS 预检） |
| 404 | JSON，-32600（reason = unknown_chain） | POST 到未知 {chain}（不读请求体、不查 key） | 否 | 检查 URL 中的链名，核对支持的链列表（须为全小写 slug） |
| 404 | 空 body | 已知链上没有 key、key 未知或被禁用；未匹配的路径（如 POST /v1、/v1/、POST /v1/{chain}/） | 否 | 在 URL 中补全链路径（/v1/{chain}）或在 x-api-key 请求头中传入有效且处于生效中的 API key（新建或轮换的 key 约几秒钟生效，请稍等片刻再试） |
| 408 | 空 | 从收完请求头到返回响应超过 35 s | 可能：已转发给节点的调用在节点应答后照常计费 | 不要无条件重试会改变状态的调用（如 eth_sendRawTransaction）；客户端断开不会撤销已转发的调用 |
| 413 | 空 | 请求体 > 2 MiB（2097152 字节），在鉴权与余额准入之后判定 | 否 | 缩减请求体大小（控制在 2 MiB 以内），拆减批量调用数量 |
| 414 / 431 | 空 | URI 过长（414）或请求头过大（431） | 否 | 缩短请求 URI 或精简 HTTP 请求头 |
| 429 | JSON，-32005 或 -32022；CU 令牌桶余量不足（-32005）时带 Retry-After；账户调用速率的 429 不带 | 桶余量不足（等补充后重试）→ -32005；单个请求的 CU 超过桶容量（等多久都不会成功，需拆小请求）→ -32022；账户调用速率上限余量不足 → -32005；单个请求的调用数超过上限（需拆小请求）→ -32022 | 否 | 若返回 -32005 且带 Retry-After，按其指定秒数等待后重试；若返回 -32022，需拆小请求或减小批次（按原样发送永远不会成功） |
| 503 | JSON，-32021，带 Retry-After | 计费状态暂时无法确认，服务端暂不受理该请求（这不是余额问题，无需充值）；刚创建的 key 在系统读到包含其账户的计费数据之前（通常几秒内）也是这个应答，稍后重试即可 | 否 | 这不是余额问题，无需充值；按 Retry-After 秒数等待后稍后重试即可 |
说明：经 Cloudflare 访问时，Cloudflare 自身还可能返回 52x（连不上源站或源站超时，例如所有实例都不可用）、1015 等错误页，那些不是本服务产生的。
JSON-RPC 错误码与计费规则
同一个错误码可能来自平台或节点，计费不同：
- 平台自身产生的错误：一律不计费；
- 节点返回的错误：原样透传并按方法权重计费，只有下表标明的节点错误码例外。
规则说明
- 节点免计费错误：节点的
-32002（批处理超时）、-32003（批响应过大）、-32600（批量被整体拒绝）表示节点提前放弃了这条调用，不计费；同一批里的 notification 也不计费。4444表示请求的区块已被节点裁剪（节点只保留约 7 天历史），不计费，不影响同批其他调用。-32000（仅限historical state ... is not available，以及 Erigon 的old data not available due to pruning...）表示请求超出节点的状态回溯窗口（约 128 块），不计费，不影响同批其他调用。Erigon 窗口约 36 天、不计费、不影响同批其他调用。 - 节点计费错误：节点返回的其他错误都算节点做了工作，按方法权重计费，例如
execution reverted（-32000或带data的3）、节点自己的-32602 invalid argument、对平台放行但节点不存在的eth_*方法返回的-32601。 - 余额准入与同步：
-32020表示账户余额不足，需要充值；-32021表示计费状态暂时无法确认，系统暂不受理该请求，这不是余额问题，无需充值，按Retry-After秒数等待后重试即可。刚创建的 key 在系统读到包含其账户的计费数据之前（通常几秒内）返回-32021，不会返回-32020；读到之后，有余额的账户照常受理，账户确实已无额度或已被删除的仍是-32020（402）。 - 上游故障：平台自产的
-32603属于上游通信故障或上游响应格式异常（upstream unavailable、no response from upstream、malformed upstream response）时，携带data.reason: upstream_unavailable；internal gateway error仅在内部异步任务 panic 或被取消的极罕见情况下产生，不代表上游故障，不带data.reason。 - Notification 计费：notification（204）照常计费。notification 在节点正常处理了整批时计费：上游 HTTP 2xx；批里有带 id 的调用时，至少一条得到了正常应答，且没有任何
-32002/-32003/-32600元素；只含 notification 的请求，上游返回 2xx 空 body 即计费。
JSON-RPC 错误码表
| 错误码 | 来源 | HTTP | 错误消息 | reason 标识 | 是否计费 | 开发者建议操作 |
|---|---|---|---|---|---|---|
| -32700 | BlockVectra | 200 | parse error | - | 否（扣 1 CU 限流令牌） | 修正 JSON 请求体语法 |
| -32600 | BlockVectra | 200 | invalid request | invalid_request | 否（扣 1 CU 限流令牌） | 修正 JSON-RPC 报文字段结构 |
| -32600 | BlockVectra | 200 | batch too large: max <N> calls | batch_too_large (+max) | 否 | 拆分为不超过上限调用的批次（单批上限通常为 100） |
| -32600 | BlockVectra | 200 | invalid request: ambiguous member name | invalid_request | 否 | 消除 JSON 对象中重复或歧义的成员名称 |
| -32601 | BlockVectra | 200 | method not available: <method> | - | 否 | 仅调用当前链允许的方法（核对支持的链方法策略） |
| -32600 | BlockVectra | 404 | unknown chain | unknown_chain | 否 | 检查 URL 中的链名 |
| -32602 | BlockVectra | 200 | eth_getLogs block range too large: max <N> blocks | - | 否 | 缩小 eth_getLogs 查询区块跨度（上限见该链规定，如 1000 块） |
| -32602 | BlockVectra | 200 | tracer not allowed | - | 否 | 改用内置原生 tracer（callTracer、flatCallTracer、prestateTracer、4byteTracer、noopTracer，或缺省） |
| -32602 | BlockVectra | 200 | trace timeout not allowed | - | 否 | 设置合法 duration 且超时时间 ≤ 30s |
| -32010 | BlockVectra | 200 | node is syncing; calls are temporarily unavailable | - | 否 | 节点同步中，稍后重试（eth_chainId 除外） |
| -32011 | BlockVectra | 200 | historical state is not available beyond the most recent <N> blocks | - | 否 | 改查较新的区块（目标区块须在状态窗口内，或避免使用 safe/finalized/earliest 标签） |
| -32000 | BlockVectra | 200 | transaction not found | not_found | 否 | 核对交易哈希（须为 0x + 64 位十六进制） |
| -32000 | BlockVectra | 200 | block not found | not_found | 否 | 核对区块哈希或高度 |
| -32000 | BlockVectra | 200 | upstream response too large | response_too_large | 否 | 缩小查询范围，拆分请求 |
| -32005 | BlockVectra | 200 | gateway overloaded, retry later | overloaded | 否 | 服务端临时过载，稍后重试 |
| -32005 | BlockVectra | 429 | rate limit exceeded | key_rate_limit / free_plan_call_limit / concurrency_limit | 否 | 降低发送频率，若带 Retry-After 按其等待 |
| -32022 | BlockVectra | 429 | request cost <N> CU exceeds burst capacity <M> CU | request_exceeds_burst | 否 | 拆小请求或批次，使单次 CU 低于突发上限 |
| -32022 | BlockVectra | 429 | request has <N> calls, exceeding the free-plan limit of <M> calls per second | free_plan_batch_too_large (+max) | 否 | 拆小批次至每秒调用限制以内，或充值升级付费方案 |
| -32603 | BlockVectra | 200 | upstream unavailable | upstream_unavailable | 否 | 上游通信故障，稍后重试 |
| -32603 | BlockVectra | 200 | no response from upstream | upstream_unavailable | 否 | 上游无响应，稍后重试 |
| -32603 | BlockVectra | 200 | malformed upstream response | upstream_unavailable | 否 | 上游响应格式异常，稍后重试 |
| -32603 | BlockVectra | 200 | internal gateway error | - | 否 | 服务端内部罕见异常，稍后重试 |
| -32020 | BlockVectra | 402 | insufficient balance | balance_exhausted / free_grant_exhausted | 否 | 前往控制台账单页充值，或等待免费额度周期补足 |
| -32021 | BlockVectra | 503 | billing data temporarily unavailable | - | 否 | 计费数据同步中（非余额问题），按 Retry-After 等待后重试 |
| 4444 | 节点 | 200 | pruned history unavailable | - | 否 | 请求的区块已被节点裁剪（节点只保留约 7 天历史），不计费，不影响同批其他调用 |
| -32000 | 节点 | 200 | historical state ... is not available | - | 否 | 请求超出节点的状态回溯窗口（约 128 块），不计费，不影响同批其他调用 |
| -32000 | 节点 | 200 | old data not available due to pruning... | - | 否（Erigon，ETH 主网） | 超出节点历史保留范围（Erigon 窗口约 36 天），不计费，不影响同批其他调用 |
| -32002 | 节点 | 200 | <node message> | - | 否 | 节点批处理超时提前放弃，不计费；同一批里的 notification 也不计费 |
| -32003 | 节点 | 200 | <node message> | - | 否 | 节点批响应过大提前放弃，不计费；同一批里的 notification 也不计费 |
| -32600 | 节点 | 200 | <node message> | - | 否 | 批量被节点整体拒绝，不计费；同一批里的 notification 也不计费 |
| 其他 | 节点 | 200 | <node message> | - | 是（方法权重） | 节点已执行并消耗资源（如 execution reverted、节点自己的 -32602、节点返回的 -32601），按方法 CU 权重计费；需检查合约调用逻辑或入参 |
Data API 计费规则
Data API 将只读链数据包装为 REST 接口，其计费与错误处理遵循以下规则：
规则说明
- “Data API 请求只在成功返回时计费。”
- “请求按 CU 计费（仅对 2xx 成功响应计费）。”
- “链专有操作不可用时（如该链不支持或 trace 覆盖范围之外），接口返回 422，不计费。”
- “超出数据覆盖范围的请求不计费，但可能计入限流。”
- “如果链未知或暂未公开，在检查 key 之前返回 HTTP 404，
error.code为not_found（不计费且不占限流；链名必须为全小写 slug）；如果是 API key 缺失、未知或被禁用时，返回 HTTP 404 且 body 为空（与 JSON-RPC 相同）。超出限流时返回 HTTP 429（error.code为rate_limited，data.reason为key_rate_limit），余额耗尽时返回 HTTP 402（error.code为insufficient_balance），两者均不计费。”
Data API 状态码表
| HTTP 状态码 | 错误代码 / 场景 | 是否计费 | 开发者建议操作 |
|---|---|---|---|
| 200 | 成功返回数据 | 是（按 Data API 操作 CU 权重） | 正常解析响应中的 data、meta 与 next_cursor |
| 400 | 请求参数无法解析或缺失必要字段 | 否 | 检查并修正请求参数 |
| 402 | 余额耗尽（error.code: "insufficient_balance"） | 否 | 前往控制台账单页查看余额与充值 |
| 404 | 链未知或暂未公开（error.code: "not_found"，在检查 key 之前判定、不占限流）、请求的对象不存在，或 API key 缺失/未知/被禁用（空 body） | 否 | 检查 URL 中的链名（须为全小写 slug）；在 x-api-key 请求头中传入有效 key |
| 409 | 请求区块高于当前已索引高度（error.code: "not_indexed_yet"，附带 indexed_through） | 否 | 改查不高于 indexed_through 的区块或稍后重试 |
| 409 | 请求区块高于 finalized_block（error.code: "finality_exceeded"） | 否 | 等待该区块最终确定，或改查更早的区块 |
| 422 | 链专有操作不可用（如该链不支持或在 trace 覆盖范围之外，error.code: "no_coverage"） | 否（照常消耗限流配额） | 通过 GET https://dev-api.blockvectra.network/v1/data/chains 核对链的能力，避免查询无覆盖的数据范围 |
| 429 | 超出调用速率限制（error.code: "rate_limited"），或单个请求的 CU 超过该 key 的突发容量（error.code: "cost_exceeds_burst"） | 否 | 降低请求频次；拆小过大的请求（超过突发容量的请求按原样重试永远不会成功） |
| 503 | 数据服务暂时不可用（error.code: "unavailable"），或该链繁忙（error.code: "gateway_overloaded"） | 否 | 稍后重试；带 Retry-After 时按其等待 |
实测说明：2026-09-30 我们用全新免费账户在正式环境实测上述规则：方法被拒（
-32601）、节点同步中（-32010）、Data API 的409 finality_exceeded与422 no_coverage均未增加用量；成功调用按GET /v1/plans公布的权重精确计量。这只是一次实测观察，不构成承诺。
定价与升级
所有计费调用的具体开销均按公布的 CU 权重计算：
- 查看各方法与操作的完整权重，请参阅方法权重表与 JSON-RPC CU 计量规则。
- 了解套餐价格与结算细则，请参阅定价页。
- 升级至付费方案：充值后不再受免费套餐的每秒调用次数上限约束；每个 key 仍有 CU 速率与突发上限。