本番環境のアプリケーションと AI エージェントで Developer Knowledge API または Developer Knowledge MCP サーバーをクエリする場合は、高いパフォーマンスを実現するために、エラー処理と割り当て管理が必要です。
このガイドでは、次の方法について学びます。
- HTTP 429 レスポンスに対して、ジッターを伴う切り捨て型指数バックオフを実装します。
- 正規の gRPC エラーコード（
INVALID_ARGUMENT、PERMISSION_DENIED、RESOURCE_EXHAUSTED）を処理します。 - MCP 接続のタイムアウトと再試行ロジックを管理します。
- 割り当て管理とキャッシュ保存のベスト プラクティスを適用します。
HTTP 429 レート制限と指数バックオフ
リクエスト レートがデフォルトの API 割り当てを超えると、サービスは HTTP 429 Too Many Requests エラーを返します。サービスへの過負荷を回避するため、アプリケーションはジッターを伴う切り捨て型指数バックオフを使用して再試行ロジックを実装する必要があります。
切り捨て型指数バックオフ
次の式を使用して再試行遅延を計算します。
retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)
次のパラメータを使用して、再試行遅延を計算します。
initial_delay: 最初の再試行の遅延（1.0 秒など）。max_delay: バックオフの最大上限（例: 32.0 秒）。attempt: 現在の再試行回数（0、1、2、...）。jitter: スレッド同期のスパイク（サンダリング ハード問題）を防ぐための 0 ～ 1.0 秒のランダム値。
gRPC エラー処理
gRPC 経由でサービスにアクセスするアプリケーションは、標準の grpc.StatusCode 値を検査する必要があります。
標準の gRPC ステータス コード
次の表に、サービスから返される標準の gRPC ステータス コードと、推奨されるクライアント処理を示します。
| gRPC ステータス コード | HTTP ステータス | 根本的な原因 | 推奨される対処方法 |
|---|---|---|---|
INVALID_ARGUMENT |
400 Bad Request |
クエリ文字列の形式が正しくない、パラメータの形式が無効である、フィールド マスクが無効である。 | 再試行しないでください。繰り返す前にリクエスト パラメータを修正します。 |
UNAUTHENTICATED |
401 Unauthorized |
API キーまたは OAuth ベアラー トークンがない、期限切れ、形式が正しくない。 | 再試行しないでください。認証情報を更新するか、有効な API キーを生成します。 |
PERMISSION_DENIED |
403 Forbidden |
API キーに権限がないか、プロジェクトで Developer Knowledge API が無効になっています。 | 再試行しないでください。Google Cloud コンソールで API が有効になっていることを確認します。 |
NOT_FOUND |
404 Not Found |
指定された parent ドキュメント パスが存在しません。リクエストされたドキュメントが見つからない場合、BatchGetDocuments はアトミックに失敗します。 |
再試行しないでください。ドキュメントのリソース名を確認します。 |
RESOURCE_EXHAUSTED |
429 Too Many Requests |
レート制限またはプロジェクトの割り当て上限を超えました。 | ジッターを伴う指数バックオフを使用して再試行します。 |
UNAVAILABLE |
503 Service Unavailable |
一時的なネットワークの切断またはサーバーの再起動。 | 指数バックオフを使用して再試行します。 |
DEADLINE_EXCEEDED |
504 Gateway Timeout |
リクエストが完了する前に、構成された RPC の期限を超過しました。 | クライアント RPC タイムアウトを増やして再試行します。 |
MCP 接続のタイムアウトとエラー管理
Developer Knowledge MCP サーバーは、https://developerknowledge.googleapis.com/mcp でホストされているリモート サービスで、HTTPS 経由でアクセスします（HTTP POST またはサーバー送信イベントを使用）。AI ホストとエージェントは、接続タイムアウトとツールエラーを適切に管理する必要があります。
ツールの実行タイムアウト
エージェントが search_documents、get_documents、answer_query を呼び出すと、ネットワーク接続が遅延した場合、ツール呼び出しがタイムアウト ウィンドウ（30 秒など）を超えることがあります。
ツールの実行タイムアウトを処理するには:
- クライアントのタイムアウトを構成する: MCP ホスト クライアント構成で、ツールの実行タイムアウトを 30 ～ 60 秒に設定します。
- ネットワークの中断を処理する: 一時的なネットワークの切断や HTTP 503 レスポンスが発生した場合は、指数バックオフを使用して失敗した HTTP リクエストを再試行します。
- エラー メッセージを検査する: 標準の JSON-RPC エラー メッセージまたは HTTP エラー ステータス コードを解析して、無効な引数と割り当ての枯渇を区別します。
割り当て管理のベスト プラクティス
API の使用を最適に保ち、予期しないレート制限を回避するには、次のベスト プラクティスに従ってください。
- 取得したドキュメント コンテンツをキャッシュに保存する: 同じページに頻繁にアクセスするアプリケーションを構築する場合は、取得した Markdown ドキュメントをローカルまたはキャッシュ（Redis など）に保存します。
- バッチ取得を使用する: 複数の
documents.getリクエストを順次実行するのではなく、documents.batchGetを使用します。 - クエリ フィールドを最適化する: 選択的なフィールド マスク（
fields=results(parent,content)）を使用して、必要なレスポンス フィールドのみをリクエストします。 - 割り当ての使用状況をモニタリングする: Google Cloud コンソールの API ダッシュボードで API リクエスト レートを追跡します。