# エラーリファレンス

> Source: https://docs.blockvectra.com/ja/errors/

このリファレンスでは、BlockVectra の各サービスのすべてのエラーコードと機械可読な `reason` 値を説明します。拒否された呼び出しが課金されるかどうか、再試行ポリシー、バックオフ時間、AI エージェントと自動クライアントに推奨する対応を記載しています。

機械可読な形式で利用するには、[/errors.json](https://docs.blockvectra.com/errors.json) から完全なカタログを JSON として取得してください。`docs_url` を含むすべてのエラーレスポンスは、このページの固定アンカーに直接リンクします：`https://docs.blockvectra.com/en/errors/#<reason>`（理由コードがないエラーでは `#-<code-number>`）。

### JSON-RPC エラー



| HTTP | エラーコード | 理由コード | 意味 | 課金 | 再試行可否 | 待機時間（Retry-After） | エージェントの対応 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | API key がありません。リクエストパス（/v1/{chain}/<api_key>）または x-api-key ヘッダーで指定してください。 | いいえ | いいえ | — | JSON-RPC エンドポイント（/v1/{chain}）では、リクエストパス（/v1/{chain}/<api_key>）または x-api-key ヘッダーで API key を指定してください。Top-up API（/v1/topup/*）では、x-api-key ヘッダーでのみ 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）。 | いいえ | いいえ | — | API key を確認してください。必要に応じてコンソールまたはプログラムによる登録で再度ログインし、新しいキーを作成してください（[セッションまたは API key を紛失した場合](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)を参照）。 |
| 403 | -32025 | `key_expired` | API key の有効期限が切れています。コンソールで新しいキーを作成してください。 | いいえ | いいえ | — | API key の有効期限が切れています。コンソールまたはプログラムによる登録で新しいキーを作成してください。 |
| 403 | -32025 | `key_cap_exhausted` | API key の CU 上限を使い切りました。コンソールで新しいキーを作成してください。 | いいえ | いいえ | — | API key の累積 CU 上限を使い切りました。コンソールまたはプログラムによる登録で新しいキーを作成してください。 |
| 503 | -32021 | `auth_unavailable` | 認証データを一時的に利用できません。 | いいえ | はい | Retry-After ヘッダーで指定された秒数待機 | サーバーが一時的にキーを検証できません。キー自体の問題ではありません。Retry-After に従って待機してから再試行してください。**キーを再作成しないでください**。 |
| 404 | -32600 | `unknown_chain` | 不明なチェーンです。 | いいえ | いいえ | — | GET /v1/chains または list_chains ツールで対応チェーンを確認し、URL パスを確認してください。 |
| 404 | 404 | `unknown_endpoint` | Data API のメソッドとパスが既知の操作に一致しません。 | いいえ | いいえ | — | Data API ドキュメントに照らしてメソッドと URL パスを確認してください。 |
| 200 | -32700 | `parse_error` | パースエラーです。 | いいえ | いいえ | — | 送信前にリクエストボディの JSON 構文が正しいことを確認してください。 |
| 200 | -32600 | `invalid_request` | 無効なリクエストです。 | いいえ | いいえ | — | リクエスト構造を確認し、jsonrpc: '2.0'、id、method フィールドを確認してから再送してください。 |
| 200 | -32602 | `invalid_params` | 許可されていない tracer です。 | いいえ | いいえ | — | メソッドのパラメータを調整し、チェーンが対応する tracer と timeout の上限を確認してください。 |
| 200 | -32602 | `logs_range_too_large` | eth_getLogs のブロック範囲が広すぎます。最大 <N> ブロックです。 | いいえ | いいえ | — | クエリのブロック範囲を 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 でこのチェーンが対応する購読を確認してください。 |
| 200 | -32602 | `logs_filter_required` | logs 購読には address または topic0（topics の最初の位置にある null 以外の値）が必要です。 | いいえ | いいえ | — | logs フィルタに address または null 以外の topic0 を指定してください。 |
| 200 | -32600 | `batch_too_large` | バッチが大きすぎます。最大 <N> コールです。 | いいえ | いいえ | — | エラーデータに記載されたコール数の上限を満たすよう、バッチを小さく分割してください。 |
| 413 | 413 | `request_too_large` | Data API のリクエストボディがサイズ上限を超えています。 | いいえ | いいえ | — | リクエストボディのサイズを小さくしてください。 |
| 200 | -32000 | `not_found` | トランザクションが見つかりません。 | いいえ | いいえ | — | 送信直後またはブロックへの取り込み直後であれば、伝播を待って再試行してください。それ以外の場合は、ブロック番号またはハッシュを確認してください。 |
| 200 | -32011 | `state_window` | 直近 <N> ブロックより前の過去の状態は利用できません。 | いいえ | いいえ | — | 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` | レート上限を超えました。 | いいえ | はい | Retry-After ヘッダーで指定された秒数待機 | Retry-After ヘッダーで指定された時間待機してから再試行するか、負荷を分散してください。 |
| 429 | rate_limited | `rate_limited` | API または GET /v1/account のリクエストレート上限を超えました（このキーで毎秒 5 リクエストを超過）。 | いいえ | はい | Retry-After ヘッダーで指定された秒数待機 | Retry-After で指定された時間待機してから再試行してください。 |
| 429 | -32005 | `concurrency_limit` | レート上限を超えました。 | いいえ | はい | Retry-After ヘッダーに従うか、実行中のコールが完了するまで待機 | クライアントの同時リクエスト数を制限し、実行中のコールが完了して枠が空いたら再試行してください。 |
| 429 | -32005 | `free_plan_call_limit` | レート上限を超えました。 | いいえ | はい | 1 秒待機してから再試行 | リクエストレートを抑えるか、チャージして有料プランの処理能力を利用してください。 |
| 429 | -32022 | `request_exceeds_burst` | リクエストのコスト <N> CU がバースト容量 <M> CU を超えています。 | いいえ | いいえ | — | 待機しても成功しません。バッチを分割するかメソッドのパラメータを縮小し、バースト容量以内に収めてください。 |
| 429 | -32022 | `free_plan_batch_too_large` | リクエストには <N> コールが含まれ、無料プランの毎秒 <M> コールの上限を超えています。 | いいえ | いいえ | — | 待機しても成功しません。コール数が無料プランの上限以内になるようバッチを分割するか、チャージしてください。 |
| 429 | -32005 | `ws_connection_limit` | このキーまたはアカウントの WebSocket 接続上限に達しました。 | いいえ | いいえ | — | 使用していない WebSocket 接続を閉じるか、既存の接続を再利用してください。 |
| 200 | -32022 | `subscription_limit` | この接続の WebSocket 購読上限に達しました。 | いいえ | いいえ | — | 既存の購読を解除するか、別の接続を開いてください。 |
| 200 | -32005 | `ws_filter_capacity` | WebSocket logs フィルタの容量上限に達しました。 | いいえ | いいえ | — | 既存の logs 購読を解除するか、フィルタの範囲を絞ってください。 |
| 200 | -32026 | `ws_push_overloaded` | WebSocket 通知キューが過負荷になっています。 | いいえ | はい | バックオフで後ほど再試行するか、再接続 | 指数バックオフで eth_subscribe を再試行するか、再接続してください。既存の購読には引き続き通知が届きます。 |
| 200 | -32005 | `overloaded` | サービスが過負荷になっています。後ほど再試行してください。 | いいえ | はい | 数秒待機して指数バックオフで再試行 | jitter を含むバックオフでリクエストを再試行してください。 |
| 402 | -32020 | `balance_exhausted` | 残高が不足しています（残高が判明している場合、error.data に balance_units と balance_cu が含まれます）。 | いいえ | いいえ | — | コンソールまたは `GET /v1/topup/deposit-address`（MCP `get_deposit_address`）で入金アドレスを取得し、オンチェーンでチャージしてください。[エージェント向けチャージガイド](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`）で入金アドレスを取得し、オンチェーンでチャージしてください。[エージェント向けチャージガイド](https://docs.blockvectra.com/en/guides/agent-topup/)を参照するか、利用可能であれば枠をリセットするか、次のサイクルの無料クレジットを待ってください。残高が判明している場合、error.data に balance_units（使い過ぎた場合は負数）と balance_cu が含まれます。 |
| 503 | -32021 | `billing_unavailable` | 課金データを一時的に利用できません。 | いいえ | はい | Retry-After ヘッダーで指定された秒数待機 | 残高の問題ではありません。新しく作成したキーは数秒以内に同期されます。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 | — | pruning 済みの履歴は利用できません。 | いいえ | いいえ | — | ブロックがノードの履歴保持範囲外です。過去のブロックは Data API で照会してください。 |
| 200 | -32000 | — | 過去の状態 ... は利用できません。pruning により古いデータを利用できません... | いいえ | いいえ | — | 状態を保持する範囲内のブロックを照会するか、過去のデータのクエリには Data API を使用してください。 |
| 200 | -32002 | — | <node message> | いいえ | はい | 数秒待機して、より小さいバッチで再試行 | バッチ内のコール数を減らして再試行してください。 |
| 200 | -32003 | — | <node message> | いいえ | いいえ | — | バッチをより小さいリクエストに分割して、レスポンスのペイロードサイズを小さくしてください。 |
| 200 | -32601 | — | <node message> | いいえ | いいえ | — | GET /v1/chains の methods.allow と methods.deny で対応メソッドを確認してください。 トランザクション送信への対応は GET /v1/chains の methods.allow によって決まります。 現在、トランザクション送信に対応していないチェーン：HyperEVM。 |
| 200 | -32603 | — | <node message> | いいえ | はい | 少し待機してから再試行 | リクエストを再試行してください。失敗が続く場合は、発生時刻を添えてサポートに報告してください。 |
| 200 | -32600 | — | <node message> | いいえ | いいえ | — | バッチ内の個々のリクエストに不適合なパラメータがないか確認し、分割して再試行してください。 |
| 200 | * | — | <node message> | はい | いいえ | — | ノードが計算を実行したため課金されました。revert の理由やデータ、またはコールのパラメータを確認してください。むやみに再試行しないでください。 |
| 408 | 408 | — | リクエストヘッダーの受信完了からレスポンスまで 35 秒を超え、タイムアウトしました。 | 可能性あり | はい | 読み取りコールは数秒待機してから再試行 | コールがノードに到達し、課金されている可能性があります。読み取りコールはバックオフで再試行してください。書き込みコール（例: eth_sendRawTransaction）は、先にハッシュでトランザクションの状態を確認してください。 |

### WebSocket 終了コード

WebSocket 接続の終了コードと推奨されるクライアントの対応。

| エラーコード | 理由コード | 意味 | 再試行可否 | 待機時間（Retry-After） | エージェントの対応 |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | アイドル状態です。 | はい | 必要に応じて再接続 | 必要に応じて再接続してください。 |
| 1003 | — | バイナリフレームは受け付けません。 | いいえ | — | 自動で再接続しないでください。UTF-8 テキストフレームのみ送信してください。 |
| 1009 | — | メッセージが大きすぎます。 | いいえ | — | 自動で再接続しないでください。大きいリクエストを分割し、1 MiB 未満に収めてください。 |
| 1012 | — | サービスが再起動しました。 | はい | jitter を含むバックオフで再接続 | jitter を含むバックオフで再接続し、再購読して、欠落したデータをバックフィルしてください。 |
| 1013 | — | チェーンを利用できません。過負荷になっています。 | はい | 指数 full-jitter バックオフで再接続 | 指数 full-jitter バックオフで再接続し、再購読して、欠落したデータをバックフィルしてください。 |
| 4402 | — | 残高が不足しています。 | いいえ | — | 自動で再接続しないでください。コンソールまたは `GET /v1/topup/deposit-address`（MCP `get_deposit_address`）で入金アドレスを取得し、オンチェーンでチャージしてください。[エージェント向けチャージガイド](https://docs.blockvectra.com/en/guides/agent-topup/)を参照するか、対象であればコンソールで枠をリセットしてください。 |
| 4404 | — | 無効な API key です。 | いいえ | — | 自動で再接続しないでください。コンソールで API key を確認するか、ローテーションしてください。 |
| 4408 | — | プッシュキューが 512 KiB（524,288 バイト）を超えると、サービスはセッションを閉じ、未配信の通知を破棄します。クライアントは close フレームを受信できない場合があります（ブラウザでは 1006 と表示）。予期しない切断も 4408 と同様に扱ってください。 | はい | バックオフで再接続し、購読を減らすか読み取りを高速化 | 予期しない切断（close フレームを受信できず、ブラウザでは 1006 と表示）を 4408 と同様に扱ってください。バックオフで再接続し、購読を再確立して、eth_getLogs で欠落したデータをバックフィルしてください。購読を減らすか、読み取りを高速化してください。 |
| 4429 | — | プッシュのレート上限を超えました。 | はい | バックオフで再接続するか、購読を削減 | 購読を減らすか、バックオフで再接続してください。 |
| 4503 | — | 課金情報を利用できません。 | はい | 指数 full-jitter バックオフで再接続 | 指数 full-jitter バックオフで再接続し、再購読してください。 |

### Data API エラー

/v1/data/{chain}/ のブロックチェーン Data API エンドポイントで返されるエラー。

| HTTP | エラーコード | 理由コード | 意味 | 課金 | 再試行可否 | 待機時間（Retry-After） | エージェントの対応 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | クエリパラメータが重複しているか、クエリ文字列が無効か、リクエスト形式が不正です。 | いいえ | いいえ | — | クエリパラメータを確認してください。limit などのパラメータが最大 1 回しか現れず、クエリパラメータが有効であることを確認してください。 |
| 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 に設定されていません。 | いいえ | いいえ | — | ブロック範囲（from_block から to_block）を <= 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`）で入金アドレスを取得し、オンチェーンでチャージしてください。[エージェント向けチャージガイド](https://docs.blockvectra.com/en/guides/agent-topup/)を参照するか、無料枠の補充を待ってください。 |
| 429 | cost_exceeds_burst | — | 単一リクエストのコストがキーのバースト容量を超えています。 | いいえ | いいえ | — | リクエストを小さく分割してください。そのまま再試行しても成功しません。 |
| 503 | gateway_overloaded | — | Data API の処理容量を一時的に利用できません。 | いいえ | はい | Retry-After: 1 秒 | このアカウントのキーとチェーン全体で同時リクエスト数を減らし、Retry-After に従って待機してから再試行してください。error.data.reason は null です。 |

### コンソール、アカウント、faucet API エラー

/v1/ の管理、キー発行、認証、faucet エンドポイントで返されるエラー。

| HTTP | エラーコード | 理由コード | 意味 | 課金 | 再試行可否 | 待機時間（Retry-After） | エージェントの対応 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 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` | Sign-In with Ethereum（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 がサーバーのホストと一致しません。 | いいえ | いいえ | — | domain と uri が challenge で返されたサーバーのホストに一致することを確認してください。 |
| 400 | siwe_invalid | `signature` | SIWE の暗号署名の検証に失敗しました。 | いいえ | いいえ | — | 指定したアドレスに対応する秘密鍵でメッセージが署名されていることを確認してください。 |
| 409 | key_limit_reached | `active_keys` | 有効な（失効していない）API key の数がアカウントの上限に達しました。 | いいえ | いいえ | — | 新しいキーを作成する前に、使用していない既存のキーを失効させてください。 |
| 409 | no_reset_available | `nothing_to_reset` | 残高がすでにリセット後の目標額以上です。リセットの機会は保持されます。 | いいえ | いいえ | — | 現在はリセット不要です。残高を使い切ってからリセットの機会を使用してください。 |
| 429 | rate_limited | `daily_creations` | アカウントの 24 時間あたりのキー作成上限に達しました。 | いいえ | はい | 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 から新しい OAuth ログインフローを開始してください。 |
| 400 | login_code_invalid | — | ログインコードが不明、有効期限切れ、または使用済みか、PKCE verifier が一致しません。 | いいえ | いいえ | — | ログインをやり直して、新しいログインコードを取得してください。 |
| 401 | unauthenticated | — | セッションがないか、セッショントークンが無効、有効期限切れ、または失効済みです。Top-up API（/v1/topup/*）では、x-api-key の代わりに Authorization ヘッダーに Bearer 以外のトークンまたは無効なトークンを指定した場合にも発生します。 | いいえ | いいえ | — | 再度ログインして新しい Bearer セッショントークンを取得してください。Top-up API では、Authorization ヘッダーの代わりに 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 をローテーションしようとしました。 | いいえ | いいえ | — | 新しいキーを作成するか、有効なキーをローテーションしてください。 |
| 409 | no_reset_available | — | このアカウントには枠をリセットする機会が残っていません。 | いいえ | いいえ | — | コンソールまたは `GET /v1/topup/deposit-address`（MCP `get_deposit_address`）で入金アドレスを取得し、オンチェーンでチャージしてください。[エージェント向けチャージガイド](https://docs.blockvectra.com/en/guides/agent-topup/)を参照するか、次のプロモーションサイクルを待ってください。 |
| 413 | payload_too_large | — | リクエストボディが 64 KiB のサイズ上限を超えています。 | いいえ | いいえ | — | リクエストボディのサイズを 64 KiB 未満にしてください。 |
| 503 | signup_paused | — | 新規ユーザー登録が全体で一時停止されています。既存ユーザーのログインには影響しません。 | いいえ | はい | 後ほど登録を再試行 | 新規ユーザー登録は一時停止中です。稼働状況を確認し、後ほど再試行してください。 |
| 503 | usage_unavailable | — | 利用量のレポートサービスを一時的に利用できません。 | いいえ | はい | 数秒待機して再試行 | /usage エンドポイントのみに影響します。他のエンドポイントは通常どおり利用できます。少し待って再試行してください。 |
| 500 | internal | — | 予期しないサーバーエラーです。 | いいえ | はい | 少し待機してから再試行 | 指数バックオフでリクエストを再試行してください。 |
| 400 | invalid_address | `invalid_address` | 受取先アドレスの形式またはチェックサムが無効です。 | いいえ | いいえ | — | 0x に続く 40 文字の 16 進数を使用し、小文字または EIP-55 チェックサム付きにしてください。data.field（/address）を確認してください。 |
| 503 | faucet_empty | `faucet_empty` | faucet の残高が受け取り申請分とトランザクション手数料を賄うのに不足しています。 | いいえ | はい | Retry-After ヘッダーで指定された秒数待機 | Retry-After に従って待機してから再試行してください。受理されたレスポンスがないまま、テスト用 ETH が送信済みだと判断しないでください。 |
| 503 | service_unavailable | `service_unavailable` | faucet の受け取り申請処理を一時的に利用できないか、前回の申請の receipt がまだありません。 | いいえ | はい | Retry-After ヘッダーで指定された秒数待機 | Retry-After に従って待機してから再試行してください。受理されたレスポンスがないまま、テスト用 ETH が送信済みだと判断しないでください。 |

### Push API エラー

/v1/push/ の Webhook 購読管理とイベント履歴で返されるエラー。

| HTTP | エラーコード | 理由コード | 意味 | 課金 | 再試行可否 | 待機時間（Retry-After） | エージェントの対応 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 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 です。 | いいえ | いいえ | — | アカウントの有効なキーを使用してください。 |
| 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 を確認し、コンソールで新しいキーを作成してください。 |
| 403 | key_expired | — | API key の有効期限が切れています。 | いいえ | いいえ | — | アカウントの有効期限内のキーを使用してください。 |
| 404 | not_found | — | ルート、メソッド、または購読が見つかりません。 | いいえ | いいえ | — | パス、メソッド、および購読の所有権を確認してください。 |
| 409 | limit_reached | — | アカウントの購読数またはアドレスペア数の上限に達しました。 | いいえ | いいえ | — | data.limit と data.max を確認し、購読またはアドレスを減らしてください。 |
| 413 | request_too_large | — | リクエストボディがルートの上限を超えています。 | いいえ | いいえ | — | アドレスのバッチを分割するか、ボディのサイズを小さくしてください。 |
| 422 | chain_not_available | — | チェーンがプッシュに対応していないか、購読に含まれていません。 | いいえ | いいえ | — | GET /v1/push/chains と購読対象のチェーンを確認してください。 |
| 422 | chains_required | — | 少なくとも 1 つのチェーンが必要です。 | いいえ | いいえ | — | 空でない chains オブジェクトを指定してください。受信を停止するには offline ステータスを使用してください。 |
| 422 | confirmations_out_of_range | — | 確認数がチェーンの許容範囲外です。 | いいえ | いいえ | — | data.min と data.max の範囲内で confirmations を選択してください。 |
| 422 | destination_not_allowed | — | 受信 URL が許可されていません。 | いいえ | いいえ | — | data.rule を確認してください。userinfo と fragment を含まない、ポート 443 の HTTPS ホスト名を使用してください。 |
| 422 | block_out_of_range | — | ブロック範囲が利用可能な replay または履歴の対応範囲外です。 | いいえ | いいえ | — | data.min_block と data.max_block を使用して範囲を調整してください。 |
| 429 | cost_exceeds_burst | — | 履歴リクエストのコストがキーのバースト容量を超えています。 | いいえ | いいえ | — | 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)では、イベントの重複排除、レシートの確認、欠落データのバックフィル、reorg 時の整合処理を追加しています。利用量の計測については[課金ルール](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/)で利用条件と共通エラーコードへの対応を確認してください。