哪些情況不計費：錯誤碼與計費規則

BlockVectra 以計算單位（CU）計量請求。JSON-RPC 與 Data API 呼叫僅在取得回應後才計費。本指南彙整 HTTP 狀態碼、JSON-RPC 呼叫與 Data API 的計費判定規則，並提供開發人員建議採取的動作。

HTTP 狀態碼與計費規則

HTTP 層回應的計費判定與處理規則如下：

注意：經由 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 錯誤碼表

Data API 計費規則

Data API 將唯讀鏈上資料包裝為 REST 端點。其計費與錯誤處理遵循以下規則：

規則詳細內容

• 僅 2xx 成功回應會計費。
• 超出涵蓋範圍而無法使用的操作（例如不支援的鏈，或超出追蹤涵蓋範圍的區塊）會傳回 HTTP 422 no_coverage，這不計費，但會計入速率限制。
• HTTP 401、402、404 與 429 回應不計費。關於回應標頭（x-bv-meter: 1），請參閱 HTTP 狀態碼與計費規則。

Data API 狀態碼表

查詢餘額（GET /v1/account）

API key 持有者可以直接查詢餘額與 key 配額詳細資料，不會產生任何計費，也不會扣除計算單位（CU）：

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。

回應範例：

{
  "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. 前往帳單頁面：前往帳單頁面。
3. 取得你的專用地址：在鏈上儲值卡片中，複製你帳戶的專用儲值地址或掃描 QR code。
4. 轉帳資金：僅使用頁面上列出的支援網路與 USDC / USDT / USDG 進行轉帳。支援的網路與最低儲值金額顯示於控制台。
5. 自動入帳：交易在鏈上被偵測到後會顯示為「處理中」；入帳後，額度會自動加入你的餘額。

重要注意事項：

• 僅使用控制台中明確列出的網路與代幣。不支援的鏈或錯誤代幣的轉帳無法自動入帳。
• 請確認每筆轉帳都達到控制台所示的最低儲值金額。
• 首次付費儲值入帳後，你的帳戶會升級為付費帳戶，並移除免費方案的每秒呼叫限制。

Agent 或伺服器程式可以使用 API key 直接呼叫儲值端點；請參閱 Agent 程式化儲值指南。

Webhook 推送計費

推送對已送達的資料事件、成功的歷史查詢與可計費的地址日分別採用不同的權重。除事件歷史外的管理呼叫、失敗的送達嘗試、自動重試與控制事件皆免費。每個已送達的事件只收取一次費用；客戶重放，以及重組後重新送達的規範事件，都是新的計費送達。地址費用採用每個訂閱在 UTC 當日上線期間的最大地址數；帳戶的免費地址額度由各訂閱共用，較舊的訂閱優先使用。同一個地址出現在兩個訂閱中會計為兩次；新增鏈會改變事件費用，但不會改變地址費用。

設定方式請參閱區塊鏈 Webhook API 指南，簽章驗證與送達復原亦同。穩定幣付款指南涵蓋收據驗證與輪詢回填；WebSocket 訂閱使用自身的連線與通知計量。請求錯誤列於錯誤參考。下列權重來自 GET /v1/plans。

下一步

• 瀏覽資料集目錄，查看 BlockVectra 索引的全部資料集。
• 查看免費方案與定價，確認你的帳戶包含的內容。
• 登入控制台建立 API key。