# 錯誤參考

> Source: https://docs.blockvectra.com/zh-hant/errors/

本參考文件收錄 BlockVectra 服務的完整錯誤碼與機器可讀原因碼（`reason`），明確標示被拒絕呼叫的計費規則、重試策略、退避時間以及面向 AI Agent 與自動化用戶端的建議處理動作。

如需機器讀取，可透過 [/errors.json](https://docs.blockvectra.com/errors.json) 取得完整的 JSON 格式錯誤目錄。錯誤回應中攜帶的 `docs_url` 直接連結到本頁面的穩定錨點：`https://docs.blockvectra.com/en/errors/#<reason>`（無 reason 的錯誤使用錯誤碼錨點，如 `#-<code-number>`）。

### JSON-RPC 錯誤



| HTTP | 錯誤碼 | 原因碼 | 含義 | 是否計費 | 能否重試 | 等待時間（Retry-After） | Agent 建議動作 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | 請求缺少 API key，未在請求路徑或請求標頭中提供 | 否 | 否 | — | JSON-RPC 端點（/v1/{chain}）在請求路徑（/v1/{chain}/<api_key>）或 x-api-key 請求標頭中傳入 API key；儲值端點（/v1/topup/*）僅接受 x-api-key 請求標頭。 |
| 401 | -32024 | `invalid_api_key` | API key 未知、已停用或已撤銷：JSON-RPC 與 Data API 均傳回 HTTP 401 和 invalid_api_key 錯誤信封（JSON-RPC：error.code 為 -32024、error.data.reason 為 invalid_api_key；Data API：error.code 與 error.data.reason 均為 invalid_api_key）。 | 否 | 否 | — | 檢查 key，必要時在控制台或用程式化開戶重新登入建新 key（連結[「工作階段或 API key 遺失怎麼辦」](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)小節）。 |
| 403 | -32025 | `key_expired` | API key 的有效期限已過；需在控制台建立新 key | 否 | 否 | — | API key 已到期；在控制台或透過程式化開戶建立新 key。 |
| 403 | -32025 | `key_cap_exhausted` | API key 的終身 CU 限額（建立時在 cu_cap 中設定）已用盡；需在控制台建立新 key | 否 | 否 | — | API key 終身 CU 上限已耗盡；在控制台或透過程式化開戶建立新 key。 |
| 503 | -32021 | `auth_unavailable` | 伺服器端臨時無法驗證 key，不是你的 key 有問題 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 伺服器端臨時無法驗證 key，不是你的 key 有問題；可重試，按 Retry-After 等待後重試，**不要因此重建 key**。 |
| 404 | -32600 | `unknown_chain` | 請求的鏈識別碼不存在或不受支援 | 否 | 否 | — | 透過 GET /v1/chains 或 list_chains 工具取得受支援的鏈清單，核對 URL 路徑中的鏈名。 |
| 404 | 404 | `unknown_endpoint` | Data API 請求方法與路徑不符合任何已知操作 | 否 | 否 | — | 核對請求方法與 URL 路徑是否符合 Data API 文件要求。 |
| 200 | -32700 | `parse_error` | JSON 解析錯誤，請求主體不是合法的 JSON 語法 | 否 | 否 | — | 確認請求主體為合法的 JSON 語法後再傳送。 |
| 200 | -32600 | `invalid_request` | JSON-RPC 請求格式不合法、成員名存在二義性或不是合法的物件/陣列 | 否 | 否 | — | 檢查請求主體結構；修正 jsonrpc: '2.0'、id 與 method 欄位後再傳送。 |
| 200 | -32602 | `invalid_params` | 方法參數不合法（如不支援的 tracer 或超時時間超限） | 否 | 否 | — | 調整方法參數；核對該鏈支援的 tracer 清單與超時限制。 |
| 200 | -32602 | `logs_range_too_large` | eth_getLogs 查詢的區塊跨度超過該鏈允許的上限 | 否 | 否 | — | 縮窄日誌查詢的區塊範圍至 GET /v1/chains 中的 max_logs_block_range 上限以內。 |
| 429 | -32005 | `public_rate_limit` | 公開端點的請求頻率超出上限 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 按 Retry-After 回應標頭等待後重試，或帶上 API key 請求。 [取得 API key](https://blockvectra.com/en/get-api-key/?ref=err-public)。 |
| 429 | -32005 | `public_pool_busy` | 公開端點暫時繁忙 | 否 | 是 | 遵循 Retry-After 回應標頭或等待數秒後退避重試 | 退避後重試，或帶上 API key 請求。 [取得 API key](https://blockvectra.com/en/get-api-key/?ref=err-public)。 |
| 200 | -32601 | `method_not_public` | 該方法不在公開端點支援的方法清單中 | 否 | 否 | — | 改用公開端點支援的方法，或帶上 API key 請求。 [取得 API key](https://blockvectra.com/en/get-api-key/?ref=err-public)。 |
| 200 | -32601 | `method_not_allowed` | 方法在該鏈上不可用或已被策略停用 | 否 | 否 | — | 透過 GET /v1/chains 查詢該鏈的 methods.allow 與 methods.deny 策略確認支援的方法。 哪些鏈不支援傳送交易由 GET /v1/chains 的 methods.allow 決定。 目前不支援傳送交易的鏈：HyperEVM。 |
| 200 | -32601 | `subscription_not_available` | 目標鏈不提供該 WebSocket 訂閱 | 否 | 否 | — | 透過 GET /v1/chains 查看該鏈支援的 subscriptions 訂閱類型。 |
| 200 | -32602 | `logs_filter_required` | logs 訂閱須指定合約地址（address）或 topic0（topics 的第一個位置非空） | 否 | 否 | — | 在 logs 過濾參數中指定 address 或非空的 topic0。 |
| 200 | -32600 | `batch_too_large` | 批次請求包含的呼叫數超過單批上限 | 否 | 否 | — | 將批次請求拆分為更小的批次，使單批呼叫數在上限以內。 |
| 413 | 413 | `request_too_large` | Data API 請求主體大小超過上限 | 否 | 否 | — | 減小請求主體體積後再傳送。 |
| 200 | -32000 | `not_found` | 請求的交易、區塊或資源不存在 | 否 | 否 | — | 若為剛廣播的交易或最新出塊，等待鏈同步後重試；否則核對區塊號或哈希值。 |
| 200 | -32011 | `state_window` | 歷史狀態超出節點保留的最長區塊視窗 | 否 | 否 | — | 僅查詢 GET /v1/chains 中 state_window_blocks 範圍內的區塊，或改用 Data API 查詢歷史資料。 |
| 200 | -32011 | `range_not_indexed` | 請求的歷史區間尚未完整索引 | 否 | 否 | — | 將歷史查詢縮小至已索引的區間，不要原樣重試未覆蓋的區間。 |
| 200 | -32011 | `history_not_ready` | 請求的近期歷史資料尚未完成索引 | 否 | 是 | 等待索引追上目標資料；若有 error.data.retry_after_seconds，按其等待 | 等待索引追上後重試；若傳回 error.data.retry_after_seconds，按指定秒數等待。 |
| 429 | -32005 | `key_rate_limit` | API key 的計算單元（CU）速率上限超限 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 休眠 Retry-After 指定的秒數後重試，或平攤請求流量。 |
| 429 | rate_limited | `rate_limited` | 端點或 GET /v1/account 請求頻率超限（GET /v1/account 每個 key 每秒最多 5 次請求） | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 休眠 Retry-After 指定的秒數後重試。 |
| 429 | -32005 | `concurrency_limit` | 在途並行請求數超過上限 | 否 | 是 | 遵循 Retry-After 回應標頭或等待目前呼叫完成 | 限制用戶端並行池大小，等待已有請求完成。 |
| 429 | -32005 | `free_plan_call_limit` | 免費方案每秒呼叫次數上限超限 | 否 | 是 | 等待 1 秒後重試 | 降低請求傳送頻率，或儲值升級為付費帳戶解鎖更高吞吐量。 |
| 429 | -32022 | `request_exceeds_burst` | 單次請求的 CU 權重超過單 key 突發上限容量 | 否 | 否 | — | 無需等待（等待不會成功）；須拆解批次請求或降低方法參數以適應突發容量。 |
| 429 | -32022 | `free_plan_batch_too_large` | 單批呼叫數超過免費方案每秒呼叫次數限制 | 否 | 否 | — | 無需等待；須將單批請求呼叫數拆小至免費方案限額以內，或進行儲值。 |
| 429 | -32005 | `ws_connection_limit` | 該 key 或帳戶的 WebSocket 連線數已達上限 | 否 | 否 | — | 關閉閒置的 WebSocket 連線或復用已有連線。 |
| 200 | -32022 | `subscription_limit` | 目前連線持有的訂閱數（或 newHeads 訂閱數）已達上限 | 否 | 否 | — | 退訂不需要的現有訂閱，或開啟新的連線。 |
| 200 | -32005 | `ws_filter_capacity` | 日誌過濾器容量已滿 | 否 | 否 | — | 退訂現有 logs 訂閱或使用更窄的過濾規則。 |
| 200 | -32026 | `ws_push_overloaded` | 積壓的推送通知過多，暫時無法接受新訂閱 | 否 | 是 | 使用退避稍後重試，或重新建立連線 | 結合指數退避重試 eth_subscribe，或重新建立連線；已建立的訂閱不受影響，繼續接收通知。 |
| 200 | -32005 | `overloaded` | 服務暫時過載 | 否 | 是 | 等待數秒並使用指數退避重試 | 結合抖動進行退避後重試請求。 |
| 402 | -32020 | `balance_exhausted` | 帳戶餘額不足或已耗盡；餘額已知時 error.data 附帶 balance_units 與 balance_cu | 否 | 否 | — | 鏈上儲值：在控制台或透過 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）取得儲值地址，詳見[Agent 儲值指南](https://docs.blockvectra.com/en/guides/agent-topup/)，或在控制台使用額度重設機會（如符合條件）。餘額已知時 error.data 附帶 balance_units（透支時可為負）與 balance_cu。 |
| 402 | -32020 | `free_grant_exhausted` | 免費方案週期額度已耗盡；餘額已知時 error.data 附帶 balance_units 與 balance_cu | 否 | 否 | — | 鏈上儲值：在控制台或透過 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）取得儲值地址，詳見[Agent 儲值指南](https://docs.blockvectra.com/en/guides/agent-topup/)、在控制台使用額度重設機會，或等待下一個週期補足額度。餘額已知時 error.data 附帶 balance_units（透支時可為負）與 balance_cu。 |
| 503 | -32021 | `billing_unavailable` | 計費狀態暫不可確認（新建立 key 正在同步或服務暫時繁忙） | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 非餘額問題，新建立的 key 通常數秒內完成同步；按 Retry-After 等待後重試即可。 |
| 200 | -32010 | `node_syncing` | 底層鏈節點正在同步中，呼叫暫時不可用 | 否 | 是 | 等待數秒後重試 | 等待節點同步完成，或查詢 GET /v1/status 查看狀態。 |
| 200 | -32603 | `upstream_unavailable` | 底層鏈節點暫不可用、應答超時或傳回畸形回應 | 否 | 是 | 等待數秒後重試 | 退避重試；可透過 GET /v1/status 查看節點健康度。 |
| 504 | 504 | `upstream_timeout` | 底層資料服務未在時限內應答 | 否 | 是 | 稍後重試 | 結合指數退避稍後重試請求。 |
| 200 | -32000 | `response_too_large` | 底層節點傳回的回應體超過伺服器端大小上限 | 否 | 否 | — | 縮窄查詢範圍（如縮小 eth_getLogs 區塊區間或減少 trace 請求範圍）。 |
| 200 | -32603 | `internal_error` | 處理請求時發生內部錯誤 | 否 | 否 | — | 稍後重試；若持續失敗請記錄時間並聯系支援團隊。 |
| 200 | 4444 | — | 請求的區塊已被底層節點裁剪 | 否 | 否 | — | 目標區塊已超出節點的裁剪保留期，可改用 Data API 取得歷史區塊資訊。 |
| 200 | -32000 | — | 底層節點歷史狀態不存在或資料已被裁剪 | 否 | 否 | — | 縮窄查詢到狀態視窗以內，或改用 Data API 查詢歷史資料。 |
| 200 | -32002 | — | 底層節點批次執行超時 | 否 | 是 | 等待數秒後使用較小的批次重試 | 減少單批呼叫數量後重試。 |
| 200 | -32003 | — | 底層節點批處理回應體過大 | 否 | 否 | — | 拆分批次以減小單個回應體大小。 |
| 200 | -32601 | — | 方法在該鏈上不可用或已被策略停用 | 否 | 否 | — | 透過 GET /v1/chains 查詢該鏈的 methods.allow 與 methods.deny 策略確認支援的方法。 哪些鏈不支援傳送交易由 GET /v1/chains 的 methods.allow 決定。 目前不支援傳送交易的鏈：HyperEVM。 |
| 200 | -32603 | — | 處理請求時發生內部錯誤 | 否 | 是 | 稍後重試 | 稍後重試；若持續失敗請記錄時間並聯系支援團隊。 |
| 200 | -32600 | — | 批次請求被底層節點整體放棄拒絕 | 否 | 否 | — | 檢查批次中各呼叫的參數規範；拆分後重試。 |
| 200 | * | — | 底層節點執行層傳回的業務錯誤（如合約執行回滾 execution reverted、節點參數驗證拒絕） | 是 | 否 | — | 節點已執行計算並按方法權重計費。檢查回滾原因或呼叫參數，切勿盲目原樣重試。 |
| 408 | 408 | — | 從收完請求標頭到傳回回應超過 35 秒超時 | 可能 | 是 | 讀請求等待數秒後重試 | 已轉發給節點的呼叫在節點應答後照常計費。讀請求可退避重試；寫請求（如 eth_sendRawTransaction）須先按交易哈希查狀態，切勿盲目重發。 |

### WebSocket 關閉碼

WebSocket 連線關閉碼與用戶端建議處理動作。

| 錯誤碼 | 原因碼 | 含義 | 能否重試 | 等待時間（Retry-After） | Agent 建議動作 |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | 連線空閒超時斷開 | 是 | 根據需要重新連線 | 根據需要重新連線。 |
| 1003 | — | 不支援二進位資料幀 | 否 | — | 切勿盲目自動重新連線；僅傳送 UTF-8 文本幀。 |
| 1009 | — | 單條請求訊息體積超過 1 MiB 上限 | 否 | — | 切勿盲目自動重新連線；拆分大請求以滿足 1 MiB 限制。 |
| 1012 | — | 服務重啟維護 | 是 | 退避後重新連線 | 結合抖動退避重新建立連線，重新訂閱並補全遺漏資料。 |
| 1013 | — | 目標鏈不可用或服務過載 | 是 | 使用指數退避後重新連線 | 使用指數退避與 full jitter 重新連線，重新訂閱並回溯補全遺漏資料。 |
| 4402 | — | 帳戶餘額不足 | 否 | — | 切勿盲目自動重新連線；鏈上儲值：在控制台或透過 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）取得儲值地址，詳見[Agent 儲值指南](https://docs.blockvectra.com/en/guides/agent-topup/)，或在控制台使用額度重設機會（如符合條件）。 |
| 4404 | — | API key 無效、已停用或已撤銷 | 否 | — | 切勿盲目自動重新連線；在控制台核驗或輪換 API key 後再連線。 |
| 4408 | — | 工作階段推送佇列超過 512 KiB（524,288 位元組）時伺服器端關閉連線並丟棄待發通知；用戶端可能收不到關閉幀（瀏覽器報 1006），意外斷開按 4408 處理。 | 是 | 退避重新連線，並減少訂閱或加快讀取 | 意外斷開（沒收到關閉幀，瀏覽器報 1006）按 4408 處理：退避重新連線，並減少訂閱或加快讀取；重新建立訂閱並透過 eth_getLogs 補全資料。 |
| 4429 | — | 推送訊息速率超出上限 | 是 | 減少訂閱或退避重新連線 | 減少訂閱數量或退避後重新連線。 |
| 4503 | — | 計費服務暫時不可用 | 是 | 使用指數退避後重新連線 | 使用全抖動指數退避重新連線並重新訂閱。 |

### Data API 錯誤

區塊鏈 Data API 端點（/v1/data/{chain}/）回傳的結構化錯誤。

| HTTP | 錯誤碼 | 原因碼 | 含義 | 是否計費 | 能否重試 | 等待時間（Retry-After） | Agent 建議動作 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | 查詢參數重復、查詢字串格式非法或請求格式錯誤 | 否 | 否 | — | 檢查查詢參數；確保 limit 等參數只出現一次，並核對參數格式。 |
| 409 | not_indexed_yet | — | 請求的區塊號或視窗超過 as_of_block，或哈希解析出的區塊高於 as_of_block（除尚無區塊的鏈外附帶 indexed_through） | 否 | 是 | 等待數秒至 indexed_through 到達目標區塊 | 輪詢等待至目標區塊或 to_block 不高於 indexed_through，或等待該鏈開始寫入區塊。 |
| 409 | window_too_large | — | 區塊視窗跨度超過 100,000 塊且未設定 clamp=true | 否 | 否 | — | 縮窄區塊區間至 100,000 塊以內，或在查詢參數中傳入 clamp=true。 |
| 409 | too_many_pools | — | 該代幣命中的流動性池超過 200 個，須改按池維度查詢 | 否 | 否 | — | 按具體的流動性池地址查詢，而非按代幣維度全量符合。 |
| 409 | span_exceeded | — | 請求的時間跨度超過 90 天上限 | 否 | 否 | — | 將 from_time 與 to_time 的時間跨度縮窄至 90 天以內。 |
| 422 | no_coverage | — | 該鏈不支援該特性，或請求的區塊早於歷史覆蓋起點 | 否 | 否 | — | 查詢前查看 GET /v1/data/chains 的 `features` 與 `coverage.from_block`（或免費的 GET /v1/status 的 `data_features`）。 |
| 503 | unavailable | — | 資料服務暫時不可用 | 否 | 是 | 等待數秒並使用指數退避重試 | 使用指數退避稍後重試。 |
| 402 | insufficient_balance | — | 付費餘額或免費額度已耗盡；餘額已知時 error.data 附帶 balance_units 與 balance_cu | 否 | 否 | — | 鏈上儲值：在控制台或透過 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）取得儲值地址，詳見[Agent 儲值指南](https://docs.blockvectra.com/en/guides/agent-topup/)，或等待免費額度補足。 |
| 429 | cost_exceeds_burst | — | 單次請求的開銷超過該 key 的突發容量 | 否 | 否 | — | 把請求拆小；原樣重試永遠不會成功。 |
| 503 | gateway_overloaded | — | Data API 目前可用容量不足 | 否 | 是 | Retry-After：1 秒 | 降低本帳戶各 key、各鏈的並行請求數，按 Retry-After 等待後重試；error.data.reason 為 null。 |

### 控制台、帳戶與水龍頭 API 錯誤

管理端點、認證介面與水龍頭回傳的錯誤。

| HTTP | 錯誤碼 | 原因碼 | 含義 | 是否計費 | 能否重試 | 等待時間（Retry-After） | Agent 建議動作 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | 儲值暫停或目前沒有可用的儲值網路；新地址無法分配，但已分配的地址仍歸該帳戶 | 否 | 否 | — | 透過 GET /v1/topup/status 查詢儲值狀態；待儲值服務恢復後重試。 |
| 503 | deposit_unavailable | — | 暫時無法分配儲值地址；按 Retry-After 回應標頭重試 | 否 | 是 | 遵循 Retry-After 回應標頭（秒）並使用指數退避重試 | 按 Retry-After 回應標頭時間重試，使用指數退避策略。 |
| 400 | invalid_request | `invalid_username` | 使用者名稱格式不合法（須為英文字母、數字或下劃線） | 否 | 否 | — | 提供符合字元與長度規範的有效使用者名稱。 |
| 400 | invalid_request | `expires_at` | 到期時刻不在未來或超過最長有效期限 | 否 | 否 | — | 將 expires_at 設定為允許有效期限內（預設 365 天）的未來 RFC 3339 時間戳記，或使用 expires_in_secs。 |
| 400 | invalid_request | `cu_cap` | cu_cap 上限越界（須為 1–9007199254740991 的整數） | 否 | 否 | — | 調整 cu_cap 為 1–9007199254740991 之間的整數，或不填表示不設終身 CU 上限。 |
| 400 | siwe_invalid | `expired` | 以太坊登入（SIWE）訊息已過期或 nonce 已被使用 | 否 | 是 | 立即取得新的 challenge 並在簽名後提交 | 重新呼叫 /v1/auth/siwe/challenge 取得新的 challenge，簽名新訊息後再登入。 |
| 400 | siwe_invalid | `chain_mismatch` | SIWE 訊息中的 chainId 與伺服器端不符合 | 否 | 否 | — | 在構造 SIWE 訊息時使用 /v1/auth/siwe/challenge 傳回的 chainId。 |
| 400 | siwe_invalid | `domain_mismatch` | SIWE 訊息中的 domain 與伺服器端主機名稱不符合 | 否 | 否 | — | 確保 SIWE 訊息中的 domain 與 uri 與 challenge 傳回的主機名稱一致。 |
| 400 | siwe_invalid | `signature` | SIWE 簽名驗證失敗 | 否 | 否 | — | 確認簽名是否由訊息中指定的以太坊地址對應的私鑰簽署。 |
| 409 | key_limit_reached | `active_keys` | 未撤銷的有效 API key 數量已達帳戶上限 | 否 | 否 | — | 在建立新 key 之前，先在控制台或端點撤銷一把閒置的 key。 |
| 409 | no_reset_available | `nothing_to_reset` | 目前餘額已不低於重設目標；此次重設機會予以保留不消耗 | 否 | 否 | — | 目前無需重設；可在額度耗盡後再使用重設機會。 |
| 429 | rate_limited | `daily_creations` | 單帳戶 24 小時新建 API key 數量達到上限 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 對現有 key 進行輪換而非新建，或按 Retry-After 建議等待 24 小時視窗刷新。 |
| 429 | signup_rate_limited | `per_ip` | 目前 IP 網段的新開戶配額已用盡 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 遵循 Retry-After 回應標頭等待後再嘗試開戶。 |
| 429 | signup_rate_limited | `global` | 全局新用戶開戶頻率已達上限 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 遵循 Retry-After 回應標頭等待後再嘗試開戶。 |
| 400 | oauth_invalid | — | OAuth 授權參數錯誤，或回調的 state 未知、過期或已使用 | 否 | 是 | — | 重新從 /v1/auth/{provider}/start 發起授權流程。 |
| 400 | login_code_invalid | — | Login code 未知、過期、已被使用，或 PKCE verifier 不符合 | 否 | 否 | — | 重新發起登入以取得新的 login code。 |
| 401 | unauthenticated | — | 缺少工作階段憑證，或工作階段權杖無效、已過期或已被撤銷；呼叫儲值端點（/v1/topup/*）時，如果帶了 Authorization 頭但不是有效的控制台工作階段權杖，也會傳回這個碼 | 否 | 否 | — | 重新登入以取得新的 Bearer 工作階段權杖；呼叫儲值端點時，改用 x-api-key 請求標頭傳 API key。 |
| 403 | user_disabled | — | 帳戶已被停用 | 否 | 否 | — | 聯繫 contact@blockvectra.com 取得帳戶支援。 |
| 404 | provider_disabled | — | 該 OAuth 認證方式暫未開啟 | 否 | 否 | — | 使用以太坊錢包登入（SIWE）或其他已啟用的登入方式。 |
| 409 | identity_in_use | — | 該身份（錢包地址或 OAuth 帳號）已被其他帳戶綁定 | 否 | 否 | — | 從舊帳戶解除綁定該身份，或使用其他身份進行綁定。 |
| 409 | identity_limit_reached | — | 該帳戶綁定的身份數量已達上限（5 個） | 否 | 否 | — | 解除綁定不需要的舊身份後再綁定新身份。 |
| 409 | last_identity | — | 不能解除綁定帳戶唯一的身份 | 否 | 否 | — | 先綁定其他身份，然後才能解除綁定目前身份。 |
| 409 | key_not_active | — | 無法對已禁用、已撤銷或已到期的 API key 進行輪換 | 否 | 否 | — | 建立新的 API key，或僅對處於 active 狀態的 key 進行輪換。 |
| 409 | no_reset_available | — | 目前帳戶沒有可用的額度重設機會 | 否 | 否 | — | 鏈上儲值：在控制台或透過 `GET /v1/topup/deposit-address`（MCP 工具 `get_deposit_address`）取得儲值地址，詳見[Agent 儲值指南](https://docs.blockvectra.com/en/guides/agent-topup/)，或等待後續活動週期。 |
| 413 | payload_too_large | — | 請求主體超過 64 KiB 大小上限 | 否 | 否 | — | 減小請求主體體積，確保在 64 KiB 以內。 |
| 503 | signup_paused | — | 全局新用戶註冊暫時熔斷暫停，已有用戶可照常登入 | 否 | 是 | 稍後重試註冊 | 新用戶註冊暫時維護；請稍後再試，已有帳戶登入不受影響。 |
| 503 | usage_unavailable | — | 用量統計服務暫時不可用（僅影響 /usage） | 否 | 是 | 等待數秒後重試 | 僅影響 /usage 端點，其他端點正常可用；稍後重試查詢用量即可。 |
| 500 | internal | — | 伺服器端發生未預期的內部錯誤 | 否 | 是 | 稍後重試 | 使用指數退避稍後重試。 |
| 400 | invalid_address | `invalid_address` | 收款地址格式或校驗和（checksum）無效 | 否 | 否 | — | 使用 0x 加 40 位十六進位字元，小寫或符合 EIP-55 校驗和（checksum）；檢查 data.field（/address）。 |
| 503 | faucet_empty | `faucet_empty` | 水龍頭餘額不足以支付本次領取金額和交易手續費 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 按 Retry-After 等待後重試；未收到受理回應時，不要假定測試 ETH 已發放。 |
| 503 | service_unavailable | `service_unavailable` | 水龍頭領取處理暫不可用，或上一筆領取尚無回執 | 否 | 是 | 遵循 Retry-After 回應標頭（秒） | 按 Retry-After 等待後重試；未收到受理回應時，不要假定測試 ETH 已發放。 |

### 推送 API 錯誤

Webhook 訂閱管理與事件歷史介面（/v1/push/）回傳的錯誤。

| HTTP | 錯誤碼 | 原因碼 | 含義 | 是否計費 | 能否重試 | 等待時間（Retry-After） | Agent 建議動作 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | 請求欄位、地址、分頁或區塊區間無效。 | 否 | 否 | — | 檢查 data.field 與 data.invalid，修正請求。 |
| 401 | missing_api_key | — | 缺少 x-api-key。 | 否 | 否 | — | 在 x-api-key 請求標頭中提供 API key。 |
| 401 | invalid_api_key | — | API key 未知、已停用或已撤銷。 | 否 | 否 | — | 使用本帳戶有效的 key。 |
| 402 | insufficient_balance | — | 事件歷史查詢餘額或免費額度已耗盡。 | 否 | 否 | — | 查看 data.reason（balance_exhausted 或 free_grant_exhausted）及可用的 data.balance_units / data.balance_cu；透過 data.topup_url 或 data.deposit_address_url 儲值。 |
| 403 | key_cap_exhausted | — | 事件歷史查詢所用 API key 的 CU 總額度已耗盡。 | 否 | 否 | — | 查看 data.cu_cap，在控制台建立新 key。 |
| 403 | key_expired | — | API key 已過期。 | 否 | 否 | — | 使用本帳戶未過期的 key。 |
| 404 | not_found | — | 路由、方法或訂閱不存在。 | 否 | 否 | — | 檢查路徑、方法與訂閱所屬帳戶。 |
| 409 | limit_reached | — | 帳戶訂閱數或地址訂閱對數達到上限。 | 否 | 否 | — | 查看 data.limit 與 data.max，減少訂閱或地址。 |
| 413 | request_too_large | — | 請求主體超過端點限制。 | 否 | 否 | — | 拆分地址批次或縮小請求主體。 |
| 422 | chain_not_available | — | 鏈不可用於推送或未加入該訂閱。 | 否 | 否 | — | 核對 GET /v1/push/chains 與訂閱的 chains。 |
| 422 | chains_required | — | 至少需要指定一條鏈。 | 否 | 否 | — | 提供非空 chains 物件；停止監聽時使用 offline 狀態。 |
| 422 | confirmations_out_of_range | — | 確認數超出該鏈範圍。 | 否 | 否 | — | 選擇 data.min 到 data.max 範圍內的 confirmations。 |
| 422 | destination_not_allowed | — | 接收 URL 不符合要求。 | 否 | 否 | — | 檢查 data.rule，使用連接埠 443 的 HTTPS 主機名稱，不含用戶資訊或 fragment。 |
| 422 | block_out_of_range | — | 區塊範圍超出可重放或歷史查詢範圍。 | 否 | 否 | — | 按 data.min_block 與 data.max_block 調整區塊範圍。 |
| 429 | cost_exceeds_burst | — | 歷史查詢費用超過 key 的突發容量。 | 否 | 否 | — | 查看 data.reason（request_exceeds_burst）與 data.max，提高突發容量後再試；原樣重試無效。 |
| 429 | rate_limited | — | 管理端點或歷史查詢達到速率限制。 | 否 | 是 | 等待 Retry-After 指定的秒數。 | 歷史查詢查看 data.reason（key_rate_limit 或 free_plan_call_limit）；等待 Retry-After 指定秒數並降低請求頻率或並行。 |
| 500 | internal_error | — | 服務發生異常。 | 否 | 否 | — | 保留 x-request-id 並聯系支援。 |
| 503 | auth_unavailable | — | API key 驗證暫不可用。 | 否 | 是 | 等待 Retry-After 指定的秒數。 | 等待 Retry-After 指定秒數後重試。 |
| 503 | billing_unavailable | — | 歷史查詢計費狀態暫不可用。 | 否 | 是 | 等待 Retry-After 指定的秒數。 | 等待 Retry-After 指定秒數後重試。 |
| 503 | upstream_unavailable | — | 推送服務暫不可達。 | 否 | 是 | 等待 Retry-After 指定的秒數。 | 等待 Retry-After 指定秒數後重試。 |
| 503 | service_unavailable | — | 推送服務或地址容量暫不可用。 | 否 | 是 | 等待 Retry-After 指定的秒數。 | 等待 Retry-After 指定秒數後重試。 |

Webhook 訂閱或重播錯誤請參閱 [Push 傳遞復原指南](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay)。接收端請先實作[原始主體簽名驗證](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures)；[穩定幣收款範例](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks)提供事件去重、收款驗證、缺口回填與重組核對路徑。計量方式見[計費規則](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing)，連線型訂閱見 [WebSocket 重新連線](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff)。

遇到 `logs_range_too_large` 時，檢視 [eth\_getLogs 方法參數](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/)，並依[區塊範圍限制與分段查詢指南](https://docs.blockvectra.com/en/guides/getlogs-block-range/)縮小查詢跨度。

Robinhood Chain 上的水龍頭領取資格及共用錯誤碼的處理方式，見[測試網水龍頭指南](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/)。