Следите за использованием ключа, пока не упёрлись в лимит
Наблюдение за заголовками квоты по ходу работы показывает приближение к лимиту задолго до того, как запрос будет отклонён.
Обработка ответа 429 без потери запроса
Код состояния 429 это не такой же сбой, как 400 или 404. Он означает, что запрос был составлен правильно и сработал бы, но ваш лимит на текущий период исчерпан.
Как выглядит ответ
HTTP/1.1 429 Too Many Requests
X-Quota-Limit: 2500
X-Quota-Used: 2500
X-Quota-Free-Remaining: 0
X-Credits-Remaining: 0.00
X-Quota-Reset: 2026-09-22T00:00:00Z
{
"status": "error",
"error": {"code": "quota_exceeded", "message": "Daily quota exceeded"}
}Не отбрасывайте запрос
Самая распространённая ошибка состоит в том, чтобы обрабатывать 429 так же, как 400: записать в журнал как сбой и двигаться дальше. Исходный поиск, который хотел выполнить пользователь или ваш скрипт, по-прежнему совершенно корректен, его просто нужно выполнить позже или с другими учётными данными. Поместите исходное содержимое запроса в очередь на повтор, а не отбрасывайте его.
Чтение времени сброса
Заголовок X-Quota-Reset в ответе 429 точно сообщает, когда сбрасывается дневной лимит. Фоновое задание может ждать до этого времени, а затем возобновить обработку очереди, а не опрашивать сервер снова и снова и не угадывать фиксированный интервал повтора.
Второй сценарий, к которому стоит подготовиться
429 не всегда означает, что весь дневной лимит израсходован. Если X-Key-IPs-Used достиг X-Key-IPs-Limit, ключ может временно получать отказ с нового исходного адреса, даже когда запросы с его обычных адресов по-прежнему проходили бы. От того, какой заголовок на самом деле объясняет 429, исчерпание квоты или лимит IP-слотов, зависит, что это исправит: в одном случае ожидание сброса, а в другом сокращение числа разных машин, использующих один и тот же ключ.
Два способа обойти лимит прямо сейчас
Если ждать нельзя, есть два немедленных варианта: пополнить предоплаченный баланс по 0,0001 € за запрос или перейти на ключ Unlimited за 50 € в месяц, если это повторяющаяся ситуация, а не разовый всплеск. Оба варианта снимают дневной потолок, из-за которого и возник 429.
Разделение лимитов ключа и лимитов сети
Поскольку бесплатный лимит общий для всей подсети /24 для IPv4 или /48 для IPv6, 429 может возникнуть из-за трафика с других адресов той же сети, а не только из-за использования вашего собственного ключа. Проверяйте X-Quota-Network-Used вместе с X-Quota-Used, чтобы различить эти две ситуации, прежде чем решать, действительно ли переход на другой ключ что-то исправит.
Ошибка, которой стоит избегать
Немедленный повтор неудачного запроса в плотном цикле, как только пришёл 429, лишь добавляет ещё больше неудачных вызовов к уже исчерпанному лимиту и ни на шаг не приближает вас к работающему запросу. Выжидайте до времени сброса из заголовка или разумную фиксированную задержку, если код не читает заголовки, а не бомбардируйте эндпоинт снова сразу же.
Если воспринимать 429 как «повторите чуть позже», а не как «это не удалось», очередь плавно проходит через сброс квоты, не теряя работу. Подробности о структуре ошибок во всём API приведены на странице ошибок, а текущие варианты лимитов на странице цен.