Аутентификация и публичное исключение
Для защищённых GET-запросов к https://api.redditgateway.com используйте X-API-Key: <ключ> либо Authorization: Bearer <ключ>. Обе схемы поддерживаются. Это аутентификация ключом архива, без Reddit OAuth. Храните секрет в защищённой серверной конфигурации, не в клиентском коде и не в журналах диагностики. Cookie Secure HttpOnly обслуживает сессию панели счёта и не заменяет заголовок для получения данных вашим приложением.
/v1/status доступен без ключа и бесплатно. Его статический ответ описывает назначение сервиса и подтверждает ответ HTTP-приложения. Маршрут не опрашивает поисковый движок, не проверяет наличие записей и не возвращает баланс. В собственном мониторинге отделяйте эту проверку от наблюдения за реальным защищённым запросом. Ответ статуса не подтверждает доступность архива для конкретного ключа.
HTTP 400 означает неправильные параметры, 401 — отсутствующий или недействительный ключ, 402 — недостаточный баланс, 429 — ограничение частоты. Разделяйте обработчики причин. После 401 проверьте конфигурацию, после 402 остановите платные задания, после 429 ограничьте число повторов и выдержите задержку. Пустой успешный ответ не является ошибкой аутентификации и сам по себе не требует регенерации ключа.
Маршруты, фильтры и структура данных
/v1/search ищет публикации и комментарии. /v1/posts дополнительно ограничивает тип публикациями, /v1/comments — комментариями. Разрешены q, subreddit, author, kind, from, to, min_score, limit и page; id для этих маршрутов не предусмотрен. Значения kind — post и comment. Для поиска обоих типов через search не задавайте этот фильтр. q выполняет текстовый поиск, а не произвольный язык запросов или анализ тональности.
/v1/item?id=... требует id и ищет одну запись, не обходя автоматически ответы или родителей. /v1/subreddits принимает только prefix и limit для поиска названий сообществ. prefix не является фильтром маршрутов содержимого. Счётчики сообществ не гарантируют точную глобальную перепись. Произвольный URL Reddit передать для загрузки нельзя; дополнительные фильтры по parent_id и link_id отсутствуют.
from и to принимают YYYY-MM-DD в UTC и фильтруют created_utc, а не дату попадания записи в архив. День to включается полностью. min_score — числовой порог оценки, без сортировки и без оценки качества ответа. Результат содержит data, pagination и credits. Документы плоские, поля могут отсутствовать; локальная группировка по присутствующим parent_id и link_id не гарантирует полной цепочки связанных сообщений.
Ограничения, итоги и стоимость ошибок
limit и page принимают значения от 1 до 100; каждый запрос получает одну страницу. Внутренний порядок _doc не означает время вставки, хронологию, релевантность или оценку. Локальная сортировка меняет только полученную выборку. Дробление диапазона дат помогает организовать работу, но не доказывает полного охвата или уникальности. Не гарантированы фиксированные даты покрытия, неизменность повторных результатов или постоянное хранение архивных записей.
Читайте pagination.total вместе с pagination.relation: eq — точное число для запроса, gte — нижняя граница, unknown — отсутствие надёжного итога, возможно null. Точный итог не означает, что все совпадения скачаны или вся история Reddit представлена в архиве. Сохраняйте возвращённые признаки has_more и window_exhausted, чтобы описывать фактические границы ответа. Не подменяйте неизвестный итог нулём в своей отчётности.
Успешное получение стоит один кредит, даже если результат пуст. Некорректный запрос не списывает баланс, сбой источника возвращает резерв. Клиентский тайм-аут или разрыв соединения может произойти после оплаченного успеха. Успешный повтор оплачивается отдельно, а ошибка вашей базы данных после получения ответа не превращает его в возвращаемый платёж. Сохраняйте ответ до обновления локального указателя прогресса.
