Все пределы API собраны здесь: что ограничено, сколько и что ответит Gratio при превышении. Почему пределы такие и как вести рассылки, не упираясь в них, — в статье Темп и лимиты.
Как читать ответы при превышении:
- ждёт — запрос не отклоняется: он встаёт в очередь и выполняется чуть позже;
429,469— отказ с паузой: повторите послеRetry-After. Gratio при таком отказе к мессенджеру не обращается;400— отказ, который повтор не исправит: поменяйте запрос.
Запросы к API
| Что | Предел | При превышении |
|---|---|---|
| Запросов с одного IP-адреса | 30 в секунду, кратковременно — до 60 | 429 |
| Тело JSON | 100 КБ | 500 too_large |
| Тело запроса с файлом | 100 МБ | 413 |
Файл по ссылке (sendFileByUrl) |
100 МБ | 400 file_too_large |
| Ожидание в очереди темпа канала | до 30 секунд | дольше — 429 + Retry-After |
| Ожидание, пока Gratio обновляет сеансы каналов | до 15 секунд | дольше — 503 unavailable + Retry-After |
| Обрыв связи с мессенджером посреди отправки | Gratio ждёт до 15 секунд и повторяет с тем же ключом | 503 outcome_unknown — повторите с тем же clientMessageId |
receiveTimeout в receiveNotification |
0–60 секунд, по умолчанию 5 | больше 60 считается как 60 |
Тайм-аут HTTP-клиента ставьте от 60 секунд на отправку — запрос может ждать своей очереди. На долгий опрос — больше receiveTimeout, в примерах справки — 90 секунд.
Темп запросов к мессенджеру
Действует в MAX и Telegram. У WhatsApp — свои правила качества, они ниже.
| Действие | Темп | При превышении |
|---|---|---|
| Отправка сообщений и файлов | 1 в секунду на канал | ждёт |
| Правка, удаление, реакция, «прочитано» | 2 в секунду | ждёт |
| Чтение: история, сообщение, профиль, файл | 4 в секунду | ждёт |
| Групповые методы | 1 раз в 2 секунды | ждёт |
| Создание группы | 1 раз в 5 минут | 429 too_frequent |
| «Печатает» в один чат | 1 запрос к мессенджеру в 2,5–4 секунды | частые вызовы продлевают индикатор |
Поиск по номеру
checkAccount и отправка по номеру +79991234567 проверяют номер одинаково: с одним кэшем и в один предел.
| Канал | Предел | После отказа мессенджера | Ответ хранится |
|---|---|---|---|
| MAX | 6 в минуту; сверх — запрос ждёт до 30 секунд, дольше — 469 |
пауза 5 минут | час |
| Telegram | 20 в час; сверх — сразу 469 |
пауза час | час |
60 в час; сверх — 469, повтор через 30 минут |
— | 30 дней |
Отказ — 469 rate_limited с Retry-After. Ответ «нет аккаунта» тоже хранится: повтор вернёт "fromCache": true.
Правила качества WhatsApp
| Правило | Предел | code |
|---|---|---|
| Первое сообщение — в новый чат или собеседнику, молчавшему 30 дней | не чаще 1 в минуту, не больше 200 в сутки | first_message_gap, first_message_limit |
| Первые сообщения нового номера | первые 10 дней — не больше 20 в сутки | first_message_limit |
| Одинаковый текст первого сообщения | не больше 10 в час | same_text_limit |
| Сообщения без ответа собеседника | до 3 за 2 минуты, одно напоминание через сутки, дальше — стоп до ответа | no_reply_limit, follow_up_too_early |
| WhatsApp ограничил номеру новые чаты | первые сообщения — на паузе сутки | restricted |
| Создание группы | не чаще раза в 5 минут, с одним участником | group_tempo |
| Добавление в группу | не чаще 1 человека в минуту, только тех, кому номер писал | group_tempo, member_not_engaged |
| Исходящий звонок | не чаще раза в 20 секунд | call_tempo |
Отказ с паузой — 429 и Retry-After, без паузы — 400. Ответы в текущих диалогах — собеседник писал за последние 30 дней — пределы первых сообщений не ограничивают. Подробно — в статье WhatsApp.
Тексты и файлы
| Что | MAX | Telegram | Почта | |
|---|---|---|---|---|
| Текст сообщения, символов | 4 000 | 4 096 | 65 536 | 100 000 |
| Файл | 100 МБ | 100 МБ; фото больше 10 МБ уходит документом | 100 МБ | письмо целиком — 20 МБ |
| Правка своего сообщения | да | пока Telegram разрешает правку | 15 минут после отправки | — |
| Удаление у всех | своё | своё; в группе, где аккаунт админ, — и чужое | своё — 48 часов; админ группы — и чужое | — |
Текст длиннее предела — 400 text_too_long. Правка после срока — 400 edit_expired в Telegram и 400 edit_window в WhatsApp, удаление своего старше 48 часов в WhatsApp — 400 revoke_window.
| Что | Предел | При превышении |
|---|---|---|
«Печатает» (typingTime) |
1000–20000 мс | 400 validation |
| Варианты опроса | от 2 до 12, без повторов | 400 validation |
| Опрос в Telegram | вопрос — до 255 символов, вариант — до 100 | длиннее Gratio обрезает |
| Телефон в контакте (sendContact) | от 10 цифр | 400 validation |
Срок закрепа в WhatsApp (duration в pinMessage и unpinMessage) |
24 часа, 7 или 30 дней, по умолчанию 7 дней | другое значение округляется вверх до ближайшего, больше 30 дней — до 30 |
Уведомления
| Что | Предел | Что будет |
|---|---|---|
| Хранение неподтверждённого уведомления | 24 часа | истекает и больше не приходит |
| Хранение подтверждённых, отравленных и истёкших | 7 дней | удаляются |
| Ответ вебхука | 30 секунд | неудача, повтор через 1, 5, 15, 60, 300 секунд, дальше каждые 5 минут |
| Неудачи вебхука подряд | час или 20 попыток — что раньше | уведомление уходит в отравленные, очередь идёт дальше |
| Отравленных в ответе getDeadNotifications | 100 за раз, старые первыми | следующие — после возврата или удаления этих |
| Возврат отравленных | хранятся ещё 24 часа с момента возврата | — |
| Реакции на чужие сообщения в группах MAX | в 20 группах с самыми свежими сообщениями — за секунды, в остальных — до ~30 минут | сообщения старше 48 часов не отслеживаются |
| Чужих сообщений под наблюдением в группе MAX | 50 свежих | — |
Подробно о реакциях — Реакция.
Подписки
| Что | Предел | При превышении |
|---|---|---|
| Подписок на канал | 5, служебные тоже считаются | 409 limit |
| Имя подписки | латиница, цифры, ., _, -, до 64 символов; имена на gratio- заняты |
400 validation |
| Адрес подписки | http(s), до 500 символов, публичный хост |
400 validation, внутренняя сеть — 400 bad_url |
| Секрет подписки | 16–128 символов | 400 validation |
| Повторы доставки | пока уведомлению нет 24 часов | истекает |
Отказы 3xx и 4xx, кроме 408 и 429 |
5 попыток | уведомление уходит в отравленные подписки |
| Время в подписи доставки | расходится с вашими часами не больше чем на 300 секунд | отклоните доставку |
Подробно — subscriptions и Проверка подписи.
Догон после простоя
| Что | Предел | При превышении |
|---|---|---|
| Сообщений на чат | 500; у почты — 200 писем | syncGap с reason: "too_deep" |
| Чатов | 100 | syncGap с reason: "too_many_chats" |
Что делать с syncGap — в статье syncGap.
История и контакты
| Что | Предел | Что будет |
|---|---|---|
count в getChatHistory |
1–200, по умолчанию 100 | больше 200 считается как 200 |
| Повтор той же истории в MAX | 5 секунд | ответ из кэша |
minutes в lastIncomingMessages и lastOutgoingMessages |
по умолчанию 1440 — сутки | — |
| Сообщений в одном ответе этих методов | 1000 | за период их больше — уменьшите minutes |
| Свежесть getContactInfo | MAX — до часа; Telegram — при каждом запросе, фото — 10 минут; WhatsApp — «О себе» и фото раз в 6 часов | ответ из кэша |
| Свежесть getGroupData в MAX | 15 минут; сбрасывается, когда группа меняется | ответ из кэша |
Участников в getGroupData |
Telegram — до 200; MAX и WhatsApp — все | — |
Группы
| Что | Предел | При превышении |
|---|---|---|
| Создание группы | 1 раз в 5 минут на канал | 429 too_frequent; в WhatsApp — 429 group_tempo |
| Изменения групп в MAX и Telegram | 1 раз в 2 секунды | ждёт |
| Название группы | MAX — до 100 символов, Telegram — до 128; WhatsApp — от 1 до 25 | длиннее обрезается; в WhatsApp — отказ bad_name |
| Участники при создании в WhatsApp | один | 400 group_tempo |
| Добавление в WhatsApp | 1 человек в минуту, только те, кому номер писал | 200 с false и причиной group_tempo или member_not_engaged |
| Удаление группы у всех в MAX | только владелец | 200 с false и причиной admin_required |
Каналы и сообщества
Действует в Telegram и MAX. Предел общий на канал: параллельные запросы его не обходят.
| Что | Предел | При превышении |
|---|---|---|
| Вступление в группу или канал | не чаще раза в минуту, до 20 в час и 40 в сутки | 429 too_frequent |
| Поиск, разбор ников и ссылок, превью, похожие каналы | 60 в час; joinChat тратит одну попытку |
429 too_frequent |
Проверка приглашений Telegram t.me/+… |
10 в час; ответ хранится 5 минут | 429 too_frequent |
| Пауза от мессенджера | сколько попросил мессенджер, не меньше минуты | 469 rate_limited |
| Каналы и супергруппы аккаунта Telegram | 500, с Telegram Premium — 1000 | 400 chats_too_much |
| Результатов searchChats | 1–100, по умолчанию 20; MAX отдаёт до 50 | — |
| Заявок за один вызов getJoinRequests | Telegram — 100, MAX — 500 | — |
| Название дополнительной ссылки в createInviteLink | 32 символа | длиннее обрезается |
Ответ already — аккаунт уже в чате — предел вступлений не тратит. Сколько вступлений уже было — getJoinLimits.
Истории
Действует в Telegram.
| Что | Предел | При превышении |
|---|---|---|
| Срок истории | 24 часа; 6, 12 и 48 часов — с Telegram Premium | 400 bad_period |
| Сколько историй | лимиты Telegram: активных, в неделю, в месяц; без Premium ниже | 429 story_limit |
| Зрителей в getStoryViews | 100 | — |
Звонки
| Что | Предел | При превышении |
|---|---|---|
| Разговор через API | MAX — один на канал | 409 busy; второй входящий звонит на телефонах как обычно |
| Исходящий звонок | не чаще раза в 20 секунд | MAX — 429 too_frequent, WhatsApp — 429 call_tempo |
| Ответить на входящий в MAX | пока звонит, до 90 секунд | звонок звонит на телефонах как обычно |
| Ожидание ответа на исходящий в MAX | 45 секунд | endReason: "no_answer" |
Длительность (maxDurationSeconds) |
1–3600 секунд, по умолчанию 600 | сервер кладёт трубку, endReason: "max_duration" |
| Очередь звука собеседнику | 5 минут | 400 audio_queue_full |
| Звук для медленного слушателя callAudio | около 5 секунд | старые кадры теряются, разговор не страдает |
Почта
| Что | Предел | При превышении |
|---|---|---|
| Письмо с вложениями | 20 МБ | 400 too_large |
| Писем в сутки с ящика | 300 — все отправки, сутки по UTC | 429 daily_limit, Retry-After: 3600 |
| Пауза между письмами | 2 секунды | ждёт |
Писем на странице getMessages и searchMessages |
1–500, по умолчанию 50 | больше 500 считается как 500 |
| Писем в одном запросе флагов, копирования, переноса и удаления | 500 | 400 validation |
Писем до подключения (since в connectMailbox) |
200 последних в каждой папке | остальные — методом getMessages |
| Ссылка входа через сервис почты | 20 минут, одноразовая | начните вход заново |
Ответ sendMessage в цепочку |
переписка не старше 30 дней | иначе — новое письмо |
Сколько писем ушло сегодня — sentToday в getMailboxInfo.
Канал и оплата
| Что | Предел | Что будет |
|---|---|---|
| Очередь уведомлений и вебхук | одни на канал: два приложения на одной очереди забирают уведомления друг у друга | каждому приложению — своя подписка, см. subscriptions |
| Срок оплаты истёк | ещё 3 дня всё работает | затем пауза |
| Пауза | 14 дней: приём, уведомления, история и чтение работают | отправка — 402 payment_required; после паузы канал снят, ключ не работает |
Подробно — в статье Каналы и ключи.
Что дальше
- Темп и лимиты — как Gratio выравнивает запросы и как вести рассылки.
- Ответы и ошибки — все коды и что повторять.
- Напоминания и рассылки без блокировок — рассылка по правилам на готовом примере.