Что означает 429?

Превышен лимит: либо суточный объём подсказок, либо число запросов в секунду. В заголовке Retry-After указано, через сколько повторять.

Чем 402 отличается от 429?

429 — упёрлись в скорость или дневной объём, само пройдёт. 402 — кончились деньги на платном пуле стандартизации или кадастра, само не пройдёт.

Почему приходит 403, если ключ рабочий?

У ключа нет прав на этот метод или домен. Права выдаются ключу в кабинете, в разделе «Ключи». После правки они подхватываются не мгновенно — дайте примерно минуту.

Стоит ли повторять запрос при 401?

Нет. Повтор с тем же ключом даст тот же ответ — проблема в самом ключе или заголовке.

Как узнать, сколько запросов осталось?

Расход по дням и методам виден в личном кабинете; там же остаток предоплаченных пулов.

Лимиты и ошибки API: 429, 403 и что с ними делать

31 июля 2026 г.

Половина проблем с интеграцией — это не баги, а неправильно обработанные коды ответа. Разберём, какие ошибки означают «повтори позже», какие «сам виноват», и как не превратить лимит запросов в лежащий сервис.

Как устроены лимиты

Лимитов два вида, и они независимы. Суточный объём подсказок — сколько запросов доступно в день: 10 000 на бесплатном тарифе, дальше по тарифу. RPS — сколько запросов в секунду принимает ключ. Упереться можно в любой из них, и в обоих случаях придёт 429.

Отдельно живут платные пулы: стандартизация и кадастр расходуют предоплаченный баланс, а не дневной объём. Когда он кончается, приходит не 429, а 402 — и это принципиально разные ситуации.

Какие ошибки повторять, а какие нет

Код	Что произошло	Что делать
401	Ключ не передан или неверен	Не повторять. Проверить заголовок авторизации
402	Кончился платный пул	Не повторять. Пополнить баланс, поставить оповещение об остатке
403	У ключа нет прав на этот метод	Не повторять. Выдать ключу нужное право в кабинете
404	Неизвестный путь или домен	Не повторять. Сверить адрес метода с документацией
429	Превышен лимит запросов	Повторить после паузы из заголовка Retry-After
503	Сервис временно недоступен	Повторить с нарастающей паузой

Тело ошибки всегда одной формы — строковый код причины, например unauthorized, forbidden_scope, insufficient_balance. Опираться в коде лучше на него, а не на текст сообщения. Полная таблица — в документации.

Как обработать 429 правильно

При превышении лимита приходит 429 с заголовком Retry-After — в нём указано, через сколько повторять. Это не рекомендация: повтор раньше времени снова упрётся в лимит и только продлит паузу.

Уважайте Retry-After — берите паузу оттуда, а не из своей константы.
Не повторяйте бесконечно: три попытки с нарастающей паузой и понятная ошибка пользователю.
Подсказки в форме повторять вообще не нужно — человек уже печатает дальше, ответ устарел.
Пакетную обработку ставьте в очередь с ограничением скорости, а не запускайте в сто потоков.

Частая ошибка в бою: подсказки шлют запрос на каждое нажатие клавиши. Задержка в 200–300 мс после последнего нажатия снижает расход запросов в несколько раз и заодно убирает мигание списка.

Что смотреть, когда что-то пошло не так

Расход по дням и методам виден в личном кабинете — по нему понятно, упёрлись вы в суточный объём или в скорость. Доступность самих сервисов — на странице статуса.

Документация Тарифы

Частые вопросы про лимиты и ошибки

Что означает 429?: Превышен лимит: либо суточный объём подсказок, либо число запросов в секунду. В заголовке Retry-After указано, через сколько повторять.
Чем 402 отличается от 429?: 429 — упёрлись в скорость или дневной объём, само пройдёт. 402 — кончились деньги на платном пуле стандартизации или кадастра, само не пройдёт.
Почему приходит 403, если ключ рабочий?: У ключа нет прав на этот метод или домен. Права выдаются ключу в кабинете, в разделе «Ключи». После правки они подхватываются не мгновенно — дайте примерно минуту.
Стоит ли повторять запрос при 401?: Нет. Повтор с тем же ключом даст тот же ответ — проблема в самом ключе или заголовке.
Как узнать, сколько запросов осталось?: Расход по дням и методам виден в личном кабинете; там же остаток предоплаченных пулов.