Ограничения, ожидание и фоновые задания

Telegram ограничивает частоту запросов от одного аккаунта. Если обращаться слишком часто, он отвечает «подождите N секунд» (FLOOD_WAIT); если продолжать запросы во время ожидания, его длительность растёт. Если писать слишком многим незнакомым людям, Telegram ограничивает аккаунт за спам. tg регулирует частоту запросов каждого профиля, выдерживает ожидание, назначенное Telegram, если оно короткое, и останавливается, если длинное. На этой странице все эти правила собраны вместе.

Частота запросов: общий лимит для профиляCopy Anchor Link

Каждый запрос tg для профиля — из команды, tg mcp, tg serve или фонового задания — попадает в общую для этого профиля очередь с ограничением частоты:

• пакет из 20 запросов выполняется сразу, поэтому обычные команды не ждут;
• после пакета — один запрос в секунду (60 в минуту), пока доступный запас не восполнится во время простоя.

Две команды, выполняемые одновременно, используют общий лимит частоты. Очередь хранится в файле в папке состояния (pace/<profile>.json), поэтому два терминала, несколько заданий store fetch --background и serve ждут своей очереди, вместо того чтобы каждое выполнялось на полной скорости. Пять параллельных загрузок не быстрее пяти последовательных и не создают большего риска. Разные профили — разные аккаунты Telegram — имеют отдельные лимиты частоты.

Если команде приходится ждать своей очереди более 5 секунд, она сообщает об этом в stderr:

waiting 12 s to keep this profile's pace with Telegram

Измените частоту запросов в файле конфигурации или для одной оболочки с помощью переменной окружения:

{ "defaults": { "requestsPerMinute": 30 } }

TG_REQUESTS_PER_MINUTE=30 tg store fetch "Book club"

0 отключает ограничение частоты. Делайте это только для профиля, для которого вы готовы допустить ограничения со стороны Telegram.

Когда Telegram просит подождатьCopy Anchor Link

store fetch и messages download --all выдерживают ожидание до 5 минут между страницами и продолжают работу; более долгое ожидание останавливает запуск, а следующий запуск продолжает с уже сохранённых данных.

Ожидание приостанавливает весь профиль. Пока оно не закончится, следующий запрос каждого процесса ждёт его окончания; запрос, которому пришлось бы ждать более 5 минут, сразу завершается с кодом выхода 8, не обращаясь к Telegram. tg doctor и tg server status показывают в flood, что приостановлено. После окончания ожидания ничего делать не нужно; tg flood clear снимает его раньше, если вы знаете, что Telegram больше не ограничивает аккаунт.

Операции записиCopy Anchor Link

• По умолчанию 30 отправок в час на профиль (sendsPerHour), с общим подсчётом во всех процессах; см. security.md.
• Ограничение за спам (PEER_FLOOD) и заморозка аккаунта блокируют все операции записи; чтение остаётся доступным. См. troubleshooting.md.
• tg никогда не повторяет отправку, если неизвестно, дошло ли сообщение; см. usage.md.

Массовое чтениеCopy Anchor Link

• store fetch: страницы до 100 сообщений, --pause между страницами (по умолчанию 1 с), 1000 сообщений за запуск, если --limit не задаёт другое значение. --estimate сначала подсчитывает запросы, не отправляя ни одного.
• messages download --all: один запрос на страницу и на файл; частота запросов к файлам также ограничивается.
• chats members list --all, chats list --all и устранение пробелов используют то же ограничение частоты.

Фоновые заданияCopy Anchor Link

store fetch --background и store gaps repair --background запускают задание, которое продолжает работу после завершения команды: не более одного задания на чат одновременно, каждое в отдельном процессе, все с общим ограничением частоты профиля. tg store jobs list показывает задания, tg store jobs cancel <job> останавливает одно после текущей страницы. См. archive.md.

БотыCopy Anchor Link

У бота свои ограничения Bot API, отдельные от ограничений аккаунта. tg соблюдает retry_after, который Telegram возвращает в ответе; длительное ожидание завершает запуск. См. bot.md.

Один вход, несколько процессовCopy Anchor Link

Каждый процесс tg открывает своё соединение, используя вход в аккаунт из профиля. Несколько процессов могут работать одновременно, но каждый из них отправляет запросы от одного и того же аккаунта, поэтому они используют общее ограничение частоты.