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

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

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

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

Реализован лимит на запросы от авторизованного пользователя (по ID пользователя).

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

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

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

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

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

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

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

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

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

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

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

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

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 минут).

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

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

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

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

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