Лимиты и квоты

429 могут вернуть три независимых механизма: месячная квота организации, лимиты частоты для ключей и лимит AI-операций на сессию для поискового ключа. AI-операции также оплачиваются кредитами (402, если кошелёк пуст); об этом раздел кредиты. Как обрабатывать каждый из ответов, описано в разделе ошибки и повторные запросы.

Месячная квота запросов

Что засчитывается. Каждая операция, переданная поисковому движку, считается за один запрос, но только при успешном ответе движка (2xx). Это поиск, мультипоиск, чтение и запись документов, импорт и изменения коллекций. Операции, которые выполняет сама контрольная плоскость, засчитываются за один запрос, когда выполняют оплачиваемую работу: например, подсказки запросов и реплики ассистента. Неудачные запросы не засчитываются. Экран «Использование» в консоли раскладывает счётчик на поиск, индексацию, AI и прочее.

Период. С подпиской квота сбрасывается при продлении периода подписки. Без подписки — в начале каждого календарного месяца. Владельцы получают письмо при 80% и при 100% квоты.

Когда квота исчерпана, все операции отвечают 429 до сброса:

{
  "message": "Quota exceeded for this organization - 5000 requests this period; resets at 2026-10-01T00:00:00.000Z.",
  "resets_at": 1790812800000
}

В Retry-After — число секунд до сброса. getEntitlement и операция проверки состояния продолжают отвечать, чтобы клиент мог узнать причину и срок.

Лимиты частоты

Поисковый ключ размещается в браузере, поэтому у него два ограничителя:

• Лимит посетителя. Не даёт автодополнению одного покупателя израсходовать бюджет всей витрины.
• Потолок ключа. Всё равно останавливает скопированный ключ, которым пользуются с множества IP.

Полные ключи размещаются на вашем сервере, и эти два ограничителя к ним не применяются. На них действуют только месячная квота и лимит ключа, если вы его задали.

Сообщение у ответов «Посетитель» и «Потолок ключа» начинается с Forbidden -, но статус у них 429. Обрабатывайте их по статусу.

Ограничения размера запросов

Раньше этих лимитов действует ограничение размера тела запроса самой хостинговой платформы, поэтому большой файл фида может быть отклонён ещё до этой проверки. Большие фиды передавайте в createIngestJob через url, а не загружайте файлом.