Rate limits
| Лимит | Значение | Когда |
|---|---|---|
messages.send per channel | 5 / секунду | POST /api/bot/spaces/{space_id}/channels/{channel_id}/messages |
messages.send per space | 60 / минуту | Все сообщения в одном space'е |
| Any bot-API call | 1000 / минуту | На любой /api/bot/* запрос |
| Инвокация команды | 20 / минуту | На пару (пользователь, бот) — POST /api/chat/{space_id}/{channel_id}/commands/invoke |
Лимит на инвокацию считается по паре (пользователь, бот) — это анти-флуд
вызовов конкретного бота одним пользователем. Подробнее о slash-командах — в
разделе Команды.
При превышении — HTTP 429. Заголовок Retry-After: <seconds> присутствует
только на путях сообщений и команд: отправка/чтение/удаление сообщений,
реакции и инвокация команды. Значение Retry-After равно окну сработавшего
лимита: per-channel — 1, per-space — 60, инвокация команды — 60.
На остальных bot-API endpoint'ах (members/roles, kick/mute, voice-*,
регистрация набора команд) общий лимит 1000 / минуту возвращает голый
429 без Retry-After — клиент должен предусмотреть фолбэк (Python SDK
при отсутствии заголовка ждёт 1.0 секунды).
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json
{"detail": "msg:ch:<bot_id>:<channel_id> > 5/1s"}
Для per-space лимита detail будет вида msg:sp:<bot_id>:<space_id> > 60/60s
с Retry-After: 60.
Лимитер работает fail-closed: если бэкенд-хранилище счётчиков временно
недоступно, сервер вернёт 429 с
detail: "rate limiter temporarily unavailable — retry shortly" — даже если
вы лимит не превышали. Заголовок Retry-After: 5 при этом проставляется только
на путях отправки сообщений и инвокации команды; на остальных bot-API
эндпоинтах (members/roles, kick/mute, voice, регистрация команд) fail-closed —
это голый 429 без Retry-After. Это transient-ошибка; повторите примерно
через 5 секунд.
SDK respect
reasonspace-bot Python SDK ретраит только 429 (до 3 раз): если есть
заголовок Retry-After — ждёт указанное в нём время, иначе фолбэк-пауза
1.0 секунды. Дополнительных действий не требуется.
Best practices
Не отправляйте 100 реакций подряд — группируйте при возможности.
Webhook events вместо GET /messages каждые 5 секунд.
Daily-digest бот в 00:00? Разнесите по 5-минутному window с random offset.
При использовании собственного клиента — реализуйте Retry-After handling.
Voice
Отдельного лимита на voice-join нет. Вызов
POST /api/bot/spaces/{space_id}/voice/{channel_id}/join подпадает под общий
лимит 1000 API-вызовов / минуту, как и любой другой запрос к bot-API.
Его 429 (как и у прочих не-message путей) приходит без Retry-After —
рассчитывайте на фолбэк-паузу на стороне клиента.
Когда лимит — слишком жёсткий
При наличии legit-case для повышения (например, broadcast-бот для большой аудитории) — откройте issue. Verified-боты смогут получить custom limits.