Обработка ошибок, ограничение частоты запросов и управление квотами

При отправке запросов к API Developer Knowledge или серверу 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 нет разрешения или API Developer Knowledge отключен в проекте. Не повторять. Проверьте, включен ли API в консоли Google Cloud.
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-сервер Developer Knowledge – это удаленный сервис, размещенный по адресу https://developerknowledge.googleapis.com/mcp и доступный по протоколу HTTPS (с использованием HTTP POST или событий, отправляемых сервером). ИИ-ведущие и агенты должны корректно обрабатывать тайм-ауты подключения и ошибки инструментов.

Тайм-ауты выполнения инструментов

Когда агент вызывает search_documents, get_documents или answer_query, время ожидания вызова инструмента может превышать установленное значение (например, 30 секунд), если сетевое подключение работает с задержками.

Чтобы обрабатывать время ожидания выполнения инструмента:

  • Настройте тайм-ауты клиента. Установите тайм-ауты выполнения инструмента на уровне 30–60 секунд в конфигурации клиента хоста MCP.
  • Обрабатывайте перебои в работе сети. Повторяйте неудачные HTTP-запросы с экспоненциальным уменьшением интервала при временных сбоях в сети или ответах HTTP 503.
  • Проверяйте сообщения об ошибках. Анализируйте стандартные сообщения об ошибках JSON-RPC или коды статуса ошибок HTTP, чтобы отличать недопустимые аргументы от исчерпания квоты.

Рекомендации по управлению квотами

Чтобы избежать неожиданных ограничений скорости и обеспечить оптимальное использование API, следуйте приведенным ниже рекомендациям.

  1. Кешируйте контент полученных документов. При создании приложений, которые часто обращаются к одним и тем же страницам, храните полученные документы Markdown локально или в кеше (например, Redis).
  2. Используйте пакетное получение данных. Вместо того чтобы выполнять несколько последовательных запросов documents.get, используйте documents.batchGet.
  3. Оптимизируйте поля запроса. Запрашивайте только необходимые поля ответа, используя селективные маски полей (fields=results(parent,content)).
  4. Отслеживайте использование квот. Отслеживайте частоту запросов к API на панели управления API в консоли Google Cloud.

Статьи по теме