# 哪些情況不計費：錯誤碼與計費規則 > Source: https://docs.blockvectra.com/zh-hant/guides/billing-rules/ BlockVectra 以計算單位（CU）計量請求。JSON-RPC 與 Data API 呼叫僅在取得回應後才計費。本指南彙整 HTTP 狀態碼、JSON-RPC 呼叫與 Data API 的計費判定規則，並提供開發人員建議採取的動作。 ## HTTP 狀態碼與計費規則 HTTP 層回應的計費判定與處理規則如下： | HTTP 狀態 | 回應內容 | 情境 | 是否計費 | 建議動作 | | --------: | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | JSON-RPC 回應（單一或批次） | 正常回應；所有 JSON-RPC 層錯誤（解析錯誤、方法拒絕、上游失敗、節點錯誤）也都是 200 | 依每次呼叫判定 | 檢查每個呼叫的 `result` 或 `error`；若傳回錯誤，請參閱下方的 JSON-RPC 錯誤處理 | | 204 | 空 | 請求中的所有呼叫都是通知 | 通知照常計費 | 無需額外動作 | | 400 | 空 | HTTP 訊息格式錯誤（無法解析請求列或標頭、無效的分塊編碼），或請求主體的兩次讀取之間超過 10 秒 | 否 | 檢查 HTTP 請求語法、標頭與傳輸連續性 | | 402 | JSON，`-32020` | 餘額不足、額度耗盡；餘額已知時，`error.data` 會包含 `balance_units` 與 `balance_cu` | 否 | 在控制台[帳單頁面](https://console.blockvectra.com/billing/)或透過 `GET /v1/topup/deposit-address`（MCP `get_deposit_address`）檢查餘額；在鏈上儲值至你帳戶的專用地址（請參閱 [Agent 儲值指南](https://docs.blockvectra.com/zh-hant/guides/agent-topup/)） | | 403 | 空 | 對 `/v1/{chain}` 或 `/v1/{chain}/{api_key}` 使用 `POST` 或 `OPTIONS` 以外的方法（無論鏈名是否已知） | 否 | 將 HTTP 請求方法改為 `POST`（或跨來源 `OPTIONS` 預檢） | | 401 | JSON，`-32024`（`missing_api_key` 或 `invalid_api_key`） | 已知鏈缺少 key、key 未知或已停用 | 否 | 在 `x-api-key` 標頭提供有效的 API key（全新或輪替的 key 需要幾秒鐘才會生效；請稍候再重試） | | 404 | JSON，`-32600`（`reason = unknown_chain`） | `POST` 至未知的 `{chain}` | 否 | 將 URL 中的鏈名與[支援的鏈](https://docs.blockvectra.com/zh-hant/chains/)核對（必須是完全相符的小寫 slug） | | 404 | 回應主體為空 | 未符合的路徑（例如 `POST /v1`、`/v1/`、`POST /v1/{chain}/`） | 否 | 在 URL 中包含鏈（`/v1/{chain}`） | | 408 | 空 | 從讀取請求標頭到傳回應超過 35 秒 | **可能**：已轉送至節點的呼叫，會在節點回應後照常計費 | 不要無條件重試會改變狀態的呼叫（例如 `eth_sendRawTransaction`）；用戶端中斷連線不會取消已轉送的呼叫 | | 413 | 空 | 請求主體 > 2 MiB（2,097,152 位元組） | 否 | 將請求主體保持在 2 MiB 以下；將批次拆分為較小的請求 | | 414 / 431 | 空 | URI 過長（414）或請求標頭過大（431） | 否 | 縮短請求 URI 或精簡 HTTP 請求標頭 | | 429 | JSON，`-32005` 或 `-32022`；速率限制（`-32005`）會附帶 `Retry-After`；突發／批次大小限制（`-32022`）不會附帶 | 權杖桶餘額耗盡 → `-32005`；單一請求的 CU 超過突發容量 → `-32022`；帳戶呼叫速率限制耗盡 → `-32005`；單一請求中的呼叫數超過限制 → `-32022` | 否 | 對於附帶 `Retry-After` 的 `-32005`，請等待指定的秒數後再重試；對於 `-32022`，請拆分請求或減小批次大小（按原樣重試永遠不會成功） | | 503 | JSON，`-32021`，附帶 `Retry-After` | 計費資料暫時無法取得；伺服器暫時拒絕請求（不是餘額問題，無需儲值）；新建的 key 在計費資料同步前（通常幾秒內）會傳回此錯誤 | 否 | 不是餘額問題，無需儲值；等待 `Retry-After` 指定的秒數後重試 | > 注意：經由 Cloudflare 存取時，Cloudflare 可能傳回 52x 或 1015 錯誤頁面；這些並非本服務所產生。 > **扣費與餘額回應標頭**：在 HTTP 請求（JSON-RPC 與 Data API 皆適用）上傳送 `x-bv-meter: 1` 時，若有至少一個呼叫計費，回應會傳回 `x-bv-cu-charged`（本次請求計費的計算單位，或批次中所有計費呼叫的總和）與 `x-bv-balance-units`（本次扣費後帳戶的剩餘餘額單位，透支時為負；餘額未知時省略）。沒有 `x-bv-meter: 1` 的請求、沒有任何計費的回應，以及 402、403、429 或 503 錯誤回應，都會省略這兩個標頭。瀏覽器指令碼可透過 CORS 存取這些回應標頭，WebSocket 則不使用。餘額會扣除未結算總用量向上取整至整數單位一次；每小時結算時向下取整，因此結算後回報的餘額可能增加最多一個單位。 ## JSON-RPC 錯誤碼與計費規則 同一個錯誤碼可能來自平台或節點，且**計費方式不同**： * **平台本身產生的錯誤**：一律不計費； * **節點傳回的錯誤**：會原樣透傳並按方法權重計費，僅下列節點錯誤碼例外。 ### 規則詳細內容 * **節點不計費的錯誤**：節點的 `-32002`（批次逾時）、`-32003`（批次回應過大）與 `-32600`（批次整體被拒絕）表示節點提早放棄呼叫；這些錯誤以及同一批次中的任何通知都不計費。節點的 `-32601`（已開放的方法未實作）與 `-32603`（節點內部失敗）在 HTTP 或 WebSocket 上都不計費，且不影響批次中的其他呼叫或通知。此外，`4444`（已修剪的區塊）與 `-32000`（超出節點狀態歷史視窗的歷史狀態，該視窗由 `GET /v1/chains` 中的 `state_window_blocks` 定義）也不計費，且不影響批次中的其他呼叫。 * **節點計費的錯誤**：節點傳回的其他錯誤若反映鏈的執行結果，則按方法權重計費，例如 `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`。 * **通知計費**：通知（204）按其方法權重計費。 ### JSON-RPC 錯誤碼表 | 錯誤碼 | 來源 | HTTP | 訊息 | 原因 | 是否計費 | 建議動作 | | -----: | ----------- | ---: | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -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: ` | - | 否 | 僅呼叫該鏈允許的方法（請參閱[支援的鏈](https://docs.blockvectra.com/zh-hant/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` | - | 否 | 設定有效的 Go duration 字串，且 timeout ≤ 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 | - | `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 | - | - | 否 | 罕見的內部錯誤，請稍後重試 | | -32020 | BlockVectra | 402 | `insufficient balance` | `balance_exhausted` / `free_grant_exhausted`（+topup\_url，且餘額已知時 +`balance_units` / `balance_cu`） | 否 | 在控制台[帳單頁面](https://console.blockvectra.com/billing/)或透過 `GET /v1/topup/deposit-address`（MCP `get_deposit_address`）檢查餘額；在鏈上儲值至你帳戶的專用地址（請參閱 [Agent 儲值指南](https://docs.blockvectra.com/zh-hant/guides/agent-topup/)） | | -32021 | BlockVectra | 503 | `billing data temporarily unavailable` | - | 否 | 計費資料同步中（不是餘額問題）；等待 `Retry-After` 秒後重試 | | 4444 | 節點 | 200 | `pruned history unavailable` | - | 否 | 請求的區塊已被節點修剪；不計費；不影響批次 | | -32000 | 節點 | 200 | `historical state ... is not available` | - | 否 | 超出節點狀態歷史視窗；不計費；不影響批次 | | -32000 | 節點 | 200 | `old data not available due to pruning...` | - | 否 | 超出節點歷史視窗（視窗由 `state_window_blocks` 決定）；不計費；不影響批次 | | -32002 | 節點 | 200 | `` | - | 否 | 節點在批次上逾時並放棄呼叫；不計費；批次中的通知也不計費 | | -32003 | 節點 | 200 | `` | - | 否 | 節點的批次回應過大而放棄；不計費；批次中的通知也不計費 | | -32601 | 節點 | 200 | `` | - | 否 | 已開放的方法未由節點實作；請改用其他支援的方法 | | -32603 | 節點 | 200 | `` | - | 否 | 節點內部失敗；請以退避方式重試 | | -32600 | 節點 | 200 | `` | - | 否 | 整個批次被節點拒絕；不計費；批次中的通知也不計費 | | 其他 | 節點 | 200 | `` | - | **是**（方法權重） | 鏈的執行結果（例如 `execution reverted`、節點 `-32602`）；請檢查合約呼叫參數 | ## Data API 計費規則 Data API 將唯讀鏈上資料包裝為 REST 端點。其計費與錯誤處理遵循以下規則： ### 規則詳細內容 * 僅 2xx 成功回應會計費。 * 超出涵蓋範圍而無法使用的操作（例如不支援的鏈，或超出追蹤涵蓋範圍的區塊）會傳回 HTTP 422 `no_coverage`，這不計費，但會計入速率限制。 * HTTP 401、402、404 與 429 回應不計費。關於回應標頭（`x-bv-meter: 1`），請參閱 [HTTP 狀態碼與計費規則](#http-status-codes-and-billing-rules)。 ### Data API 狀態碼表 | HTTP 狀態 | 錯誤碼／情境 | 是否計費 | 建議動作 | | ------: | ---------------------------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | 成功資料回應 | **是**（Data API 操作 CU 權重） | 解析回應結構中的 `data`、`meta` 與 `next_cursor` | | 400 | 請求參數格式錯誤或缺少必填欄位 | 否 | 檢查並修正查詢或主體參數 | | 402 | 餘額耗盡（`error.code: "insufficient_balance"`，餘額已知時包含 `balance_units` 與 `balance_cu`） | 否 | 在控制台[帳單頁面](https://console.blockvectra.com/billing/)或透過 `GET /v1/topup/deposit-address`（MCP `get_deposit_address`）檢查餘額；在鏈上儲值至你帳戶的專用地址（請參閱 [Agent 儲值指南](https://docs.blockvectra.com/zh-hant/guides/agent-topup/)） | | 401 | API key 缺少、未知或已停用（`error.code: "missing_api_key"` 或 `"invalid_api_key"`） | 否 | 在 `x-api-key` 標頭中傳入有效的 API key | | 404 | 鏈未知或未公開（`error.code: "not_found"`），或請求的物件不存在 | 否 | 檢查 URL 中的鏈 slug（必須完全相符的小寫）與請求路徑 | | 409 | 請求的區塊或視窗高於目前索引高度（`error.code: "not_indexed_yet"`，包含 `indexed_through`） | 否 | 查詢至 `indexed_through` 為止的區塊，或稍後重試 | | 422 | 鏈專屬操作無法使用（例如不支援的鏈或超出追蹤涵蓋範圍，`error.code: "no_coverage"`） | 否（計入速率限制） | 透過 `GET /v1/status`（免費、免 key 的 `data_features`）檢查支援的功能 | | 429 | 超出速率限制（`error.code: "rate_limited"`），或單一請求的成本超過該 key 的突發容量（`error.code: "cost_exceeds_burst"`） | 否 | 降低請求頻率；拆分過大的請求（超過突發容量的請求按原樣傳送永遠不會成功） | | 503 | 資料服務暫時無法使用（`error.code: "unavailable"`），或該鏈忙碌中（`error.code: "gateway_overloaded"`） | 否 | 稍後重試，並在有 `Retry-After` 時遵循 | ## 查詢餘額（`GET /v1/account`） API key 持有者可以直接查詢餘額與 key 配額詳細資料，不會產生任何計費，也不會扣除計算單位（CU）： ```bash curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account ``` * **免費且不計費**：`GET /v1/account` 免費。它永遠不計費、不扣除 CU，而且即使餘額為零或負數，仍會傳回 HTTP 200 與目前餘額（永遠不會傳回 402）。 * **驗證**：key 驗證僅使用 `x-api-key` 標頭（不接受路徑 key 與 Bearer 權杖）。缺少標頭會傳回 401 `missing_api_key`；無效或已撤銷的 key 會傳回 401 `invalid_api_key`。（過期的 key 會傳回 403 `key_expired`；服務暫時無法使用時會傳回 503 `auth_unavailable` 或 `billing_unavailable`，並附帶 `Retry-After`。） * **速率限制**：每個 key ID 有獨立的每秒 5 次請求限制，與 CU 計量及計費無關。超過限制會傳回 HTTP 429 `rate_limited`，並附帶 `Retry-After` 標頭。 回應欄位： * `key_id`：API key 的識別字串。 * `plan`：帳戶方案類型（帳戶擁有免費方案呼叫速率額度時為 `free`；否則為 `paid`）。 * `balance_units`：帳戶剩餘餘額，以單位表示（可為零或負數）。 * `balance_cu`：換算為計算單位（CU）的剩餘餘額。 * `balance_as_of_age_ms`：自資料來源讀取該餘額以來所經過的毫秒數。 * `key`：該 key 專屬的限制與配額詳細資料： * `cu_per_sec`：權杖桶補充速率，以每秒 CU 表示。 * `burst_cu`：權杖桶的突發容量，以 CU 表示。 * `cu_cap`：此 key 的終身 CU 上限；無上限時為 `null`。 * `cu_cap_remaining`：`cu_cap` 下的剩餘 CU；無上限時為 `null`（可為零或負數）。 * `expires_at`：RFC 3339 到期時間戳；key 永不過期時為 `null`。 回應範例： ```json { "key_id": "", "plan": "", "balance_units": , "balance_cu": , "balance_as_of_age_ms": , "key": { "cu_per_sec": , "burst_cu": , "cu_cap": , "cu_cap_remaining": , "expires_at": "" } } ``` ## 定價與升級 所有計費呼叫的具體成本由公布的 CU 權重決定： * 若要查看所有方法與操作的權重，請參閱[方法權重表](https://blockvectra.com/zh-hant/pricing/)與 [JSON-RPC CU 計量規則](https://docs.blockvectra.com/zh-hant/api/json-rpc/#cu-metering-rules)。 * 關於方案定價與結算詳細資料，請參閱[定價頁面](https://blockvectra.com/zh-hant/pricing/)。 * 升級至付費方案：進行付費儲值後會移除免費方案的每秒呼叫限制；每個 key 仍受 CU 速率與突發限制約束。 ### 鏈上儲值流程 當你的帳戶餘額不足，或需要更高的輸送量時，請在控制台依下列步驟進行鏈上儲值： 1. **登入控制台**：登入 [BlockVectra 控制台](https://console.blockvectra.com/login/?next=%2Fbilling%2F)。 2. **前往帳單頁面**：前往[帳單頁面](https://console.blockvectra.com/billing/)。 3. **取得你的專用地址**：在鏈上儲值卡片中，複製你帳戶的專用儲值地址或掃描 QR code。 4. **轉帳資金**：僅使用頁面上列出的支援網路與 USDC / USDT / USDG 進行轉帳。支援的網路與最低儲值金額顯示於控制台。 5. **自動入帳**：交易在鏈上被偵測到後會顯示為「處理中」；入帳後，額度會自動加入你的餘額。 > **重要注意事項**： > > * 僅使用控制台中明確列出的網路與代幣。不支援的鏈或錯誤代幣的轉帳無法自動入帳。 > * 請確認每筆轉帳都達到控制台所示的最低儲值金額。 > * 首次付費儲值入帳後，你的帳戶會升級為付費帳戶，並移除免費方案的每秒呼叫限制。 Agent 或伺服器程式可以使用 API key 直接呼叫儲值端點；請參閱 [Agent 程式化儲值指南](https://docs.blockvectra.com/zh-hant/guides/agent-topup/)。 ## Webhook 推送計費 推送對已送達的資料事件、成功的歷史查詢與可計費的地址日分別採用不同的權重。除事件歷史外的管理呼叫、失敗的送達嘗試、自動重試與控制事件皆免費。每個已送達的事件只收取一次費用；客戶重放，以及重組後重新送達的規範事件，都是新的計費送達。地址費用採用每個訂閱在 UTC 當日上線期間的最大地址數；帳戶的免費地址額度由各訂閱共用，較舊的訂閱優先使用。同一個地址出現在兩個訂閱中會計為兩次；新增鏈會改變事件費用，但不會改變地址費用。 設定方式請參閱[區塊鏈 Webhook API 指南](https://docs.blockvectra.com/zh-hant/guides/webhook-push/)，[簽章驗證](https://docs.blockvectra.com/zh-hant/guides/webhook-push/#verify-signatures)與[送達復原](https://docs.blockvectra.com/zh-hant/guides/webhook-push/#delivery-retries-and-replay)亦同。[穩定幣付款指南](https://docs.blockvectra.com/zh-hant/guides/stablecoin-payments/)涵蓋收據驗證與輪詢回填；[WebSocket 訂閱](https://docs.blockvectra.com/en/guides/websocket-subscriptions/)使用自身的連線與通知計量。請求錯誤列於[錯誤參考](https://docs.blockvectra.com/zh-hant/errors/)。下列權重來自 `GET /v1/plans`。 | 用量 | 計費單位 | CU | | --- | --- | --- | | `push.address_day` | 計費地址日 | 33 | | `push.history` | 成功的歷史查詢請求 | 25 | | `push.log` | 已送達的資料事件 | 150 | | `push.native_transfer` | 已送達的資料事件 | 150 | | `push.token_transfer` | 已送達的資料事件 | 150 | 每帳戶每 UTC 日免費地址數：1000 每帳戶每 UTC 日的免費地址額度，由所有訂閱組共享，與方案無關。對每個組，統計其在該日上線期間的最大地址數；按組 ID 升序分配額度。同一地址在兩個組中計為兩份；組內鏈的數量不會使地址數成倍增加。整日離線或已刪除的組不計入。對每個組，扣除分配給它的額度後，將剩餘地址數乘以 `method_weights` 中的 `push.address_day` CU 權重。目前設定的額度來自地址日計費所用的同一定價政策；它不是帳戶容量上限，也不是每個組各自獨立的額度。 範例：10 個已送達的 native.transfer 事件、2 次成功歷史查詢與 10 個計費地址日，消耗 10 × 150 + 2 × 25 + 10 × 33 = 1880 CU。計費地址日已扣除帳戶免費地址額度。 ## 下一步 * [瀏覽資料集目錄](https://blockvectra.com/zh-hant/data/)，查看 BlockVectra 索引的全部資料集。 * [查看免費方案與定價](https://blockvectra.com/zh-hant/pricing/#free)，確認你的帳戶包含的內容。 * [登入控制台](https://console.blockvectra.com/login/?next=%2Fkeys%2F)建立 API key。