Ограничения частоты запросов Публичного API

Документация описывает механизм ограничения частоты запросов в Публичном API GitVerse. Этот механизм защищает инфраструктуру от перегрузки и обеспечивает стабильную работу API для всех пользователей. Понимание ограничений частоты запросов помогает правильно организовать вызовы API и избежать блокировок.

Общее описание

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

Реализован лимит на запросы от авторизованного пользователя (по ID пользователя). Каждый авторизованный пользователь имеет свой собственный счетчик запросов.

Лимит по авторизованному пользователю

Применяется к авторизованным запросам, содержащим токен в заголовке Authorization.

  • лимит — 2000 запросов в час;
  • интервал — 1 час (3600 секунд);
  • сброс — автоматически каждый час.

⚠️ При превышении лимита все последующие запросы от этого ID будут отклоняться до сброса счетчика.

Если лимит превышен, API возвращает ответ с кодом состояния 429 Too Many Requests. Клиент должен приостановить отправку запросов и повторить попытку после времени, указанного в заголовке Retry-After.

Заголовки в ответе

Каждый ответ API (успешный или с ошибкой) содержит заголовки, позволяющие отслеживать использование лимитов. Эти заголовки нужно считывать и обрабатывать в клиентском коде для корректного управления частотой запросов.

ЗаголовокОписание
GitVerse-RateLimit-LimitМаксимальное количество запросов, разрешенных за час (например, 2000)
GitVerse-RateLimit-User-RemainingОставшееся количество запросов до достижения лимита
GitVerse-RateLimit-Retry-AfterКоличество секунд, через которое можно повторить запрос после превышения лимита
Gitverse-Ratelimit-ResetВременная метка Unix (в секундах), когда лимит будет сброшен
Retry-AfterСтандартный HTTP-заголовок, дублирующий GitVerse-RateLimit-Retry-After

Эти заголовки помогают клиентам корректно управлять частотой запросов и избегать блокировок.

Примеры ответов

Успешный запрос

Пример ответа на успешный запрос со стандартными заголовками rate limiting:

HTTP/1.1 200 OK
Date: Tue, 12 Aug 2025 17:00:00 GMT
Content-Type: application/json; charset=utf-8
GitVerse-RateLimit-Limit: 2000
GitVerse-RateLimit-User-Remaining: 1999
Vary: Origin
Cache-Control: max-age=0, private, must-revalidate, no-transform

Заголовок GitVerse-RateLimit-User-Remaining: 1999 показывает, что после этого запроса осталось 1999 запросов до достижения лимита в 2000.

Превышение ID-лимита (429 Too Many Requests)

Пример ответа при превышении лимита запросов:

HTTP/1.1 429 Too Many Requests
Date: Tue, 12 Aug 2025 17:00:00 GMT
Content-Type: application/json; charset=utf-8
GitVerse-RateLimit-Limit: 2000
GitVerse-RateLimit-User-Remaining: 0
GitVerse-RateLimit-Retry-After: 2253
Gitverse-Ratelimit-Reset: 1754917200
Retry-After: 2253
Vary: Origin
Cache-Control: max-age=0, private, must-revalidate, no-transform

Это означает, что пользователь исчерпал лимит в 2000 запросов. Повторить запрос можно через 2253 секунды (~37.5 минут). Заголовок Gitverse-Ratelimit-Reset: 1754917200 содержит точное время сброса в формате Unix timestamp.

Рекомендации для пользователей

  1. При получении 429 приостановите отправку запросов на указанное в Retry-After время. Используйте экспоненциальный backoff для повторных попыток.
  2. Используйте кэширование данных, чтобы снизить количество повторных запросов к API.
  3. Проверяйте заголовок GitVerse-RateLimit-User-Remaining перед отправкой каждого запроса. Если значение близко к нулю, снизьте частоту запросов.
  4. Планируйте интеграции с учетом лимита в 2000 запросов в час на одного пользователя. Для высоконагруженных систем рассмотрите распределение запросов между несколькими токенами.

Отладка и мониторинг

Для отладки состояния лимитов используйте следующие подходы:

  • следите за значением GitVerse-RateLimit-User-Remaining — оно уменьшается с каждым запросом. Это позволяет оценить, сколько запросов осталось до блокировки;
  • используйте Gitverse-Ratelimit-Reset для точного определения времени сброса (в формате Unix timestamp). Переведите это значение в читаемый формат даты, чтобы знать, когда счетчик обнулится;
  • логгируйте заголовки rate limit headers в ваших интеграциях. Это поможет отследить, когда и почему запросы начали отклоняться, и спланировать оптимизацию частоты вызовов.

Вид графа

Связанные страницы