哪些请求不计费：错误码与计费规则

BlockVectra 服务按计算单元（CU，Compute Unit）计量。调用仅在得到应答后计费。本文汇总 HTTP 状态码、JSON-RPC 接口以及 Data API 在不同响应和错误场景下的计费判定规则，并列出推荐的开发者处理方式。

HTTP 状态码与计费判定

HTTP 层的请求拦截与处理结果计费规则如下：

以下方法规则适用于 /v1/{chain} 与 /v1/{chain}/{api_key} 的普通 HTTP 请求，不涵盖 /v1/chains 等具名路由。有效的 WebSocket 升级按 WebSocket 能力与鉴权规则处理，不套用普通 GET/HEAD 规则。

说明：经 Cloudflare 访问时，Cloudflare 自身还可能返回 52x、1015 等错误页，那些不是本服务产生的。

扣费与余额响应头：HTTP 请求（JSON-RPC 与 Data API 均适用）携带 x-bv-meter: 1 请求头时，产生扣费的响应会返回 x-bv-cu-charged（本次请求计费的 CU，批量请求为合计值）以及 x-bv-balance-units（本次扣费后账户的剩余余额单位，透支时可为负；余额未知时不带）。未携带 x-bv-meter: 1、未产生计费的响应，以及 402、403、429、503 均不返回这两个响应头；浏览器脚本可通过 CORS 读取这两个响应头；WebSocket 不使用它们。余额扣除的是未结算用量合计向上取整到整数单位后的值；每小时结算向下取整，因此结算后所报余额可能增加最多一个单位。

JSON-RPC 错误码与计费规则

同一个错误码可能来自平台或节点，计费不同：

• 平台自身产生的错误：一律不计费；
• 节点返回的错误：原样透传并按方法权重计费，只有下表标明的节点错误码例外。

规则说明

• 节点免计费错误：节点的 -32002（批处理超时）、-32003（批响应过大）与 -32600（批量被整体拒绝）表示节点提前放弃了调用，不计费；同一批里的 notification 也不计费。节点的 -32601（已开放但节点未实现的方法）与 -32603（节点内部故障）在 HTTP 和 WebSocket 上均不计费，且不影响同批其他调用或 notification。此外，4444（区块已被裁剪）以及超出节点状态回溯窗口（以 GET /v1/chains 的 state_window_blocks 为准）的 -32000 同样不计费，且不影响同批其他调用。
• 节点计费错误：节点返回的其他错误若反映链本身的执行结果，按方法权重计费，例如 execution reverted（-32000 或带 data 的 3）、节点自己的 -32602 invalid argument。
• 余额准入与同步：-32020 表示账户余额不足，需要充值；余额已知时 error.data.balance_units 与 error.data.balance_cu 携带剩余额度（透支时可为负）。刚创建的 key 在最初几秒可能返回 -32021（503），按 Retry-After 等待后重试即可。
• 上游故障：平台自产的 -32603 属于上游通信故障或上游响应格式异常（upstream unavailable、no response from upstream、malformed upstream response）时，携带 data.reason: upstream_unavailable。
• Notification 计费：notification（204）按方法权重计费。

JSON-RPC 错误码表

Data API 计费规则

Data API 将只读链数据包装为 REST 接口，其计费与错误处理遵循以下规则：

规则说明

• 仅 2xx 成功响应计费。
• 链专有操作不可用或超出覆盖范围（如不支持的链或 trace 覆盖外）返回 HTTP 422 no_coverage，不计费但占限流配额。
• HTTP 401、402、404 与 429 响应均不计费。扣费响应头说明见上方 HTTP 状态码与计费判定。

Data API 状态码表

查询余额（GET /v1/account）

开发者与 Agent 可以直接查询当前 key 对应的余额与限额信息，无需消耗计算单元（CU）：

curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account

• 完全免费：GET /v1/account 调用自身完全免费，不计费且不产生用量扣除；即使账户余额为 0 或为负数也始终返回 HTTP 200 并携带当前余额（从不返回 402）。
• 鉴权规则：仅从 x-api-key 请求头读取 API key（不读取路径中的 key 或 Bearer token）。未带 key 返回 401 missing_api_key；key 未知、已禁用或已吊销返回 401 invalid_api_key（key 过期返回 403 key_expired；服务临时不可用时返回 503 auth_unavailable 或 billing_unavailable 并附带 Retry-After）。
• 独立限速：每个 key 每秒最多允许 5 次请求，独立于 CU 计量与计费规则；超出后返回 HTTP 429 rate_limited 并附带 Retry-After 响应头（见完整 OpenAPI 参考中的“10. Limits at a glance”）。

响应字段说明：

• key_id：API key 自身的标识 ID（不暴露数字账户 ID）。
• plan：套餐类型（free 表示账户拥有免费套餐每秒调用额度；否则为 paid）。
• balance_units：账户剩余余额（单位 units，可为 0 或负数）。
• balance_cu：按当前折算规则换算后的 CU 余额。
• balance_as_of_age_ms：服务端自底层读取该余额至今所经历的毫秒数。
• key：该 key 的限额与生命周期属性：
  • cu_per_sec：该 key 的每秒 CU 速率上限（令牌桶补充速率）。
  • burst_cu：该 key 的 CU 突发容量上限（令牌桶容量）。
  • cu_cap：该 key 的总 CU 上限；未设置时为 null。
  • cu_cap_remaining：该 key 剩余的可用 CU 额度（可为 0 或负数）；未设置上限时为 null。
  • expires_at：RFC 3339 格式的到期时间戳；永不过期时为 null。

响应示例：

{
  "key_id": "<key_id>",
  "plan": "<plan>",
  "balance_units": <integer>,
  "balance_cu": <integer>,
  "balance_as_of_age_ms": <integer>,
  "key": {
    "cu_per_sec": <integer>,
    "burst_cu": <integer>,
    "cu_cap": <integer_or_null>,
    "cu_cap_remaining": <integer_or_null>,
    "expires_at": "<expires_at_or_null>"
  }
}

定价与升级

所有计费调用的具体开销均按公布的 CU 权重计算：

• 查看各方法与操作的完整权重，请参阅方法权重表与 JSON-RPC CU 计量规则。
• 了解套餐价格与结算细则，请参阅定价页。
• 升级至付费方案：充值后不再受免费套餐的每秒调用次数上限约束；每个 key 仍有 CU 速率与突发上限。

链上充值流程

当账户余额不足或需要提升调用速率上限时，可在控制台按以下流程进行链上充值：

1. 登录控制台：登录 BlockVectra 控制台。
2. 进入账单页：进入「账单」页面（Billing）。
3. 获取专属地址：在「链上充值」卡片中复制账户专属的充值地址或扫描二维码。
4. 发起转账：只使用页面明确列出的支持网络与 USDC / USDT / USDG 转账到该专属地址。支持的网络与最低充值金额以控制台账单页为准。
5. 自动到账：检测到转账后显示为「处理中」，到账后余额自动增加。

注意事项：

• 只接受控制台列出的网络与代币。转错链或转错代币无法自动入账。
• 每笔转账请确保达到控制台注明的最低充值金额。
• 首次充值成功到账后，账户转为付费账户，解除免费套餐的每秒调用上限。

Agent 或服务器程序可用 API key 直接调用充值接口，见 Agent 程序化充值指南。

Webhook 推送计费

推送按已送达数据事件、成功历史查询与计费地址日分别计价。除事件历史外的管理调用、失败投递、自动重试与控制事件免费。每个已送达事件收取一次费用；客户重放与重组后规范链事件的重投是新的计费投递。地址费按各订阅在 UTC 日内在线期间的最大地址数计算，账户免费地址额度由各订阅共享，较早创建的订阅优先使用。同一地址放在两个订阅中计为两份；添加链只影响事件费用，不增加地址费。

接入、签名校验与投递恢复见区块链 Webhook API 指南。稳定币收款指南提供收款校验与轮询补扫路径；WebSocket 订阅使用自身的连接与通知计量规则。请求错误见错误参考。下表权重来自 GET /v1/plans。

下一步

• 浏览数据集目录，查看 BlockVectra 索引的全部数据集。
• 查看免费额度与定价，确认账户可用的方案。
• 登录控制台创建 API key。