Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Как правильно читать заголовки X-Quota-Used и X-Quota-Limit
Каждый ответ API, успешный или нет, содержит набор заголовков, которые точно показывают, где вы находитесь относительно своей квоты. Чтобы правильно их читать, нужно понимать, что считает каждый из них.
Основная пара
X-Quota-Limit это размер вашей текущей квоты: либо бесплатной дневной квоты, либо фактического лимита в рамках пакета Unlimited. X-Quota-Used показывает, сколько запросов уже учтено в этой квоте за текущий период. Вычитать одно из другого вручную не нужно, поскольку X-Quota-Free-Remaining уже делает это за вас.
HTTP/1.1 200 OK
X-Quota-Limit: 2500
X-Quota-Used: 1840
X-Quota-Free-Remaining: 660
X-Quota-Network-Used: 1840
X-Credits-Remaining: 0.00
X-Key-IPs-Used: 1
X-Key-IPs-Limit: 3
X-Quota-Reset: 2026-09-22T00:00:00ZИспользование ключа и использование сети
X-Quota-Used отражает использование, привязанное к вашему ключу, а X-Quota-Network-Used отражает использование из окружающей сети, поскольку бесплатная квота общая для всех адресов IPv4 в одной /24 и всех адресов IPv6 в одной /48, независимо от того, используется ли ключ. Если ключ вызывается с нескольких серверов из одного блока адресов, сетевой показатель будет расти быстрее, чем ожидал бы любой отдельный сервер, исходя из собственного трафика.
Пара IP-слотов
X-Key-IPs-Used и X-Key-IPs-Limit описывают совсем другое: сколько разных адресов-источников недавно использовали этот конкретный ключ, относительно скользящего лимита в два или три адреса на ключ. Ключ, который вызывается с одного сервера, будет стабильно показывать здесь 1. Ключ, используемый на нескольких не связанных между собой серверах или скопированный в скрипт, который в итоге запускается на многих машинах, будет приближаться к лимиту. За этим стоит следить отдельно от квоты запросов, поскольку это может заблокировать ключ, даже когда бесплатных запросов остаётся ещё много.
Баланс и время сброса
X-Credits-Remaining показывает ваш предоплаченный баланс, когда вы вышли за пределы бесплатной квоты и расходуете баланс по 0,0001 € за запрос. X-Quota-Reset точно сообщает, когда сбросится текущая дневная квота, и это надёжнее, чем предполагать фиксированное время по собственным часам.
Что построить на основе этих заголовков
Панель мониторинга, оповещение или просто строка журнала, которая читает эти заголовки после каждого вызова, дают актуальную картину использования без отдельного запроса отчёта, поскольку цифры приходят в ответе на уже сделанный вами запрос. Их чтение ничего дополнительно не стоит, ведь они приходят с каждым запросом, который вы и так отправляли, независимо от того, был ли он успешным или вернулся с ошибкой.
Ошибка, которой стоит избегать
Если читать эти заголовки только когда что-то идёт не так, вы узнаете о проблеме с квотой в тот же момент, что и ваши пользователи. Записывайте в журнал как минимум X-Quota-Free-Remaining и X-Credits-Remaining по регулярному расписанию или после каждого вызова в интеграции с небольшим трафиком, чтобы медленное приближение к лимиту отображалось как тенденция на панели мониторинга, а не как внезапная серия ответов 429.
Чтение заголовков квоты в каждом ответе, вместо того чтобы ждать 429, чтобы заметить проблему, это разница между плавным замедлением и неожиданным. Полный список заголовков приведён на странице лимитов запросов.