Заголовки
Успешные JSON-ответы (200) и ответ 429 несут состояние окна:
Ответ
text/event-stream потокового эндпоинта и остальные конверты ошибок (401, 403, 404, 409, 422, 503, 500) этих заголовков не несут; в каждом ответе есть только X-Request-ID. Если вы регулируете клиент по X-RateLimit-Remaining, считайте отсутствующий заголовок «неизвестно», а не нулём.
Когда окно исчерпано, API отвечает 429 rate_limit_exceeded и добавляет Retry-After (секунды до сброса окна).
Когда недоступен сам ограничитель
Ограничитель отказывает закрыто. Если его хранилище недоступно, API отвечает503 api_rate_limit_unavailable с Retry-After: 5 вместо того, чтобы пропускать запросы без учёта, и вместо вводящего в заблуждение 429. Относитесь к нему как к любой другой временной ошибке: подождите и повторите с тем же Idempotency-Key.