# 哪些请求不计费：错误码与计费规则 > 原文地址: https://docs.blockvectra.com/zh/guides/billing-rules/ BlockVectra 服务按计算单元（CU，Compute Unit）计量。调用仅在得到应答后计费，不会在请求到达时预扣。本文汇总 HTTP 状态码、JSON-RPC 接口以及 Data API 在不同响应和错误场景下的计费判定规则，并列出推荐的开发者处理方式。 ## HTTP 状态码与计费判定 [#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） | 否 | 前往控制台[账单页](https://console.blockvectra.com/zh/billing/)查看余额与充值 | | 403 | 空 | `/v1/{chain}`、`/v1/{chain}/{api_key}` 上除 `POST`、`OPTIONS` 外的方法（链名已知或未知都一样） | 否 | 将 HTTP 请求方法改为 `POST`（或跨域 `OPTIONS` 预检） | | 404 | JSON，`-32600`（`reason = unknown_chain`） | `POST` 到未知 `{chain}`（不读请求体、不查 key） | 否 | 检查 URL 中的链名，核对[支持的链](/zh/chains/)列表（须为全小写 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 错误码与计费规则 [#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 错误码表 [#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 calls` | `batch_too_large` (+max) | 否 | 拆分为不超过上限调用的批次（单批上限通常为 100） | | -32600 | BlockVectra | 200 | `invalid request: ambiguous member name` | `invalid_request` | 否 | 消除 JSON 对象中重复或歧义的成员名称 | | -32601 | BlockVectra | 200 | `method not available: ` | - | 否 | 仅调用当前链允许的方法（核对[支持的链](/zh/chains/)方法策略） | | -32600 | BlockVectra | 404 | `unknown chain` | `unknown_chain` | 否 | 检查 URL 中的链名 | | -32602 | BlockVectra | 200 | `eth_getLogs block range too large: max 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 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 CU exceeds burst capacity CU` | `request_exceeds_burst` | 否 | 拆小请求或批次，使单次 CU 低于突发上限 | | -32022 | BlockVectra | 429 | `request has calls, exceeding the free-plan limit of 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` | 否 | 前往控制台[账单页](https://console.blockvectra.com/zh/billing/)充值，或等待免费额度周期补足 | | -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 | `` | - | 否 | 节点批处理超时提前放弃，不计费；同一批里的 notification 也不计费 | | -32003 | 节点 | 200 | `` | - | 否 | 节点批响应过大提前放弃，不计费；同一批里的 notification 也不计费 | | -32600 | 节点 | 200 | `` | - | 否 | 批量被节点整体拒绝，不计费；同一批里的 notification 也不计费 | | 其他 | 节点 | 200 | `` | - | **是**（方法权重） | 节点已执行并消耗资源（如 `execution reverted`、节点自己的 `-32602`、节点返回的 `-32601`），按方法 CU 权重计费；需检查合约调用逻辑或入参 | ## Data API 计费规则 [#data-api-计费规则] Data API 将只读链数据包装为 REST 接口，其计费与错误处理遵循以下规则： ### 规则说明 [#规则说明-1] * “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 状态码表 [#data-api-状态码表] | HTTP 状态码 | 错误代码 / 场景 | 是否计费 | 开发者建议操作 | | -------: | -------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------- | | 200 | 成功返回数据 | **是**（按 Data API 操作 CU 权重） | 正常解析响应中的 `data`、`meta` 与 `next_cursor` | | 400 | 请求参数无法解析或缺失必要字段 | 否 | 检查并修正请求参数 | | 402 | 余额耗尽（`error.code: "insufficient_balance"`） | 否 | 前往控制台[账单页](https://console.blockvectra.com/zh/billing/)查看余额与充值 | | 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 权重计算： * 查看各方法与操作的完整权重，请参阅[方法权重表](https://blockvectra.com/zh/pricing/)与 [JSON-RPC CU 计量规则](/zh/api/json-rpc/#cu-计量规则)。 * 了解套餐价格与结算细则，请参阅[定价页](https://blockvectra.com/zh/pricing/)。 * 升级至付费方案：充值后不再受免费套餐的每秒调用次数上限约束；每个 key 仍有 CU 速率与突发上限。 ## 下一步 [#下一步] * [浏览数据集目录](https://blockvectra.com/zh/data/)，查看 BlockVectra 索引的全部数据集。 * [查看免费额度与定价](https://blockvectra.com/zh/pricing/#free)，确认账户可用的方案。 * [登录控制台](https://console.blockvectra.com/zh/login/?next=%2Fzh%2Fkeys%2F)创建 API key。