🎉 Версия 20.0.0. Что новенького? →
Публичный APIИспользование Публичного APIOграничения частоты запросов (Rate Limits)

Ограничения частоты запросов (Rate Limits)

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

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

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

При превышении лимитов API возвращает статус-код 429 Too Many Requests.

Реализованы два типа лимитов:

  • лимит на авторизованного пользователя (по IP-адресу);
  • глобальный лимит на все запросы к API.

Лимиты

1. Лимит по авторизованному пользователю (по IP)

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

ПараметрЗначение
Применяется кАвторизованные запросы
ИдентификаторIP-адрес клиента (извлекается из заголовка Gitverse-Client-IP)
Лимит500 запросов в час
Интервал1 час (3600 секунд)
СбросАвтоматически каждый час (по часовому окну)

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

2. Глобальный лимит на все запросы

Применяется ко всем запросам к Публичному API, включая анонимные и авторизованные.

ПараметрЗначение
Применяется кВсе запросы к Публичному API
ИдентификаторГлобальный счётчик
Лимит1 000 000 запросов в час
Интервал1 час (3600 секунд)
СбросАвтоматически каждый час

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

Порядок проверки лимитов

API проверяет лимиты в следующем порядке:

  1. IP-лимит (для авторизованных пользователей) — 500 запросов/час
  2. Глобальный лимит — 1 000 000 запросов/час

Если любой из лимитов превышен, API возвращает ответ с кодом состояния 429 Too Many Requests.

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

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

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

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

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

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

HTTP/1.1 200 OK
Date: Tue, 12 Aug 2025 17:00:00 GMT
Content-Type: application/json; charset=utf-8
GitVerse-RateLimit-Limit: 500
GitVerse-RateLimit-Remaining: 499
GitVerse-RateLimit-Retry-After: 3540
Gitverse-Ratelimit-Reset: 1754917200
Retry-After: 3540
Vary: Origin
Cache-Control: max-age=0, private, must-revalidate, no-transform

Превышение IP-лимита

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: 500
GitVerse-RateLimit-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

Это означает, что пользователь исчерпал лимит в 500 запросов. Повторить запрос можно через 2253 секунды (~37.5 минут).

Превышение глобального лимита

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: 1000000
GitVerse-RateLimit-Remaining: 0
GitVerse-RateLimit-Retry-After: 3600
Gitverse-Ratelimit-Reset: 1754920800
Retry-After: 3600
Vary: Origin
Cache-Control: max-age=0, private, must-revalidate, no-transform

Все запросы временно заблокированы. Сброс произойдеДля отладки состояния лимитов:т через 3600 секунд (1 час).

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

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

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

Для отладки состояния лимитов:

  • следите за значением GitVerse-RateLimit-Remaining — оно уменьшается с каждым запросом;
  • используйте Gitverse-Ratelimit-Reset для точного определения времени сброса (в формате Unix timestamp);
  • при массовых ошибках 429 проверьте, не исчерпан ли глобальный лимит — в этом случае проблема не в вашем IP, а в общей нагрузке на API.
Использование Публичного APIПользователи