在正式版應用程式和 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 Bearer 權杖。 | 請勿重試。重新整理憑證或產生有效的 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 使用量，並避免發生非預期的速率限制：
- 快取擷取的檔案內容：建構經常存取相同網頁的應用程式時，請在本地或快取 (例如 Redis) 中儲存擷取的 Markdown 文件。
- 使用批次擷取：使用
documents.batchGet，而非執行多個連續的documents.get要求。 - 最佳化查詢欄位：使用選擇性欄位遮罩 (
fields=results(parent,content)) 僅要求必要的回應欄位。 - 監控配額用量：在 Google Cloud 控制台 API 資訊主頁中追蹤 API 要求率。