错误处理、速率限制和配额管理

在生产应用和 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 连接超时和错误管理

开发者知识 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 使用率并避免意外的速率限制：

  1. 缓存检索到的文档内容：在构建经常访问相同页面的应用时，将提取的 Markdown 文档存储在本地或缓存（例如 Redis）中。
  2. 使用批量检索：使用 documents.batchGet 而不是执行多个连续的 documents.get 请求。
  3. 优化查询字段：使用选择性字段掩码 (fields=results(parent,content)) 仅请求所需的响应字段。
  4. 监控配额消耗情况：在 Google Cloud 控制台 API 信息中心内跟踪 API 请求速率。

相关内容