Ограничения частоты

Как это устроено

Лимит стоит не на всём API, а точечно — на маршрутах, где он действительно нужен: вход, публичные формы, страница проверки подлинности, тяжёлая проверка таблицы, письма наружу. По умолчанию маршрут ничем не ограничен.

Счёт ведётся по маршруту и по тому, кто обращается. Лимит на вход не расходуется обращениями к публичной форме и наоборот. Счётчики общие для всех процессов приложения, лежат в Redis и живут ровно одно окно.

Кто обращается, определяется так:

• запрос по токену (из кабинета или выданному через OAuth) считается на организацию — с какого бы адреса он ни пришёл. Агенты Claude и ChatGPT ходят к нам с общих облачных адресов за многих пользователей сразу, и счёт по IP делил бы один предел между чужими организациями;
• человек в кабинете и публичные адреса — по IP-адресу.

Объём выпуска ограничивается условиями организации — пробой или планом, — а не частотой запросов: см. GET /api/org/usage.

Где лимиты есть

Из адресов, доступных по токену (по токену — на организацию):

Обращения в поддержку токену закрыты (403): их пишет человек в кабинете — новое обращение не чаще 10 раз в час, ответ в нём — 30 раз в час.

Превью, MCP, пробные письма и выдача по API считаются на организацию всегда — и по токену, и из кабинета. Отказ пробного письма по частоте приходит кодом 400 с текстом «Слишком часто. Подождите N секунд и попробуйте снова». Инструменты MCP вызывают REST изнутри сервера, поэтому каждый вызов инструмента расходует и лимит /mcp, и лимит маршрута, который он вызывает: например, validate_recipients — ещё и лимит проверки.

Вход агентов через OAuth и ссылка на архив — по IP-адресу:

Публичные адреса, доступные без токена:

Формы выдачи — на сайте организации (Тильда и наш скрипт формы) и по ссылке:

У tilda-create лимит по адресу общий на все сайты сразу: Тильда шлёт со своих серверов. От накрутки там защищает суточный предел интеграции (dailyLimit).

Заявки, коды, опрос и скачивание считаются по форме или по заявке вместе с адресом, а не по одному адресу: класс школы выходит в интернет с одного IP, и общий предел отказал бы двадцатому ученику, хотя каждый заполнил форму один раз. Перебор держит общий потолок адреса во второй колонке, а подбор кода — сама заявка: после пяти неверных кодов она закрывается.

Вход и учётная запись — это адреса человека, а не программы, но лимиты на них тоже есть:

Остальные маршруты кабинета — документы, получатели, выпуск, реестр, рассылка — частотой не ограничены (через MCP — в пределах общих 300 вызовов в минуту). Это не приглашение молотить их в тысячу потоков: сервис общий, и разумный темп в ваших же интересах.

Ответ при превышении

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "Слишком много попыток. Повторите через 43 с."
}

Код ошибки — в статусе HTTP, поля statusCode в теле нет. У превью, выдачи по API и сервера MCP текст свой («Слишком много превью…», «Не больше 120 документов по API в минуту…», «Слишком часто…»), но число секунд в нём есть всегда.

Число секунд в сообщении — время до конца текущего окна. Отдельного заголовка Retry-After в ответе нет, значение придётся взять из текста.

Сервер MCP при превышении своего предела отвечает 429 с телом JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": null,
  "error": { "code": -32600, "message": "Слишком часто. Повторите через 12 с." }
}

Если же лимит сработал на маршруте внутри инструмента, сам запрос к /mcp отвечает 200, а инструмент возвращает ошибку с isError: true и текстом «Ошибка 429: …».

Как вести себя программе

1. Не гонитесь за скоростью там, где ответ не изменится: список получателей и состояние задания меняются медленно.
2. Задание выпуска опрашивайте не чаще раза в 2–3 секунды. Тысяча документов печатается минутами, а не миллисекундами. Через MCP удобнее get_job с waitSeconds: он ждёт на стороне сервера и тратит один вызов вместо двадцати.
3. Получив 429, подождите указанное число секунд и повторите. Повтор сразу же продлевает ожидание, а не сокращает его.
4. При недоступности Redis сервис считает обращения в памяти процесса. Лимит при этом становится мягче, но не исчезает.