Лимиты
Чтобы защитить сервис и обеспечить стабильную работу для всех, API применяет несколько ограничений.
Частота запросов
Лимит считается в запросах в секунду и зависит от тарифа: от 1 запроса в секунду на бесплатном тарифе до 10 на корпоративном. Лимит общий на пользователя: запросы всех его токенов складываются.
При превышении возвращается 429. В теле ответа есть поле retryAfter — через
сколько секунд можно повторить, то же значение приходит в заголовке
Retry-After. В каждом ответе API есть заголовки X-RateLimit-Limit и
X-RateLimit-Remaining — лимит и остаток в текущей секунде.
{ "message": "API rate limit exceeded", "retryAfter": 1 }
Сделайте паузу на указанное время и повторите запрос (экспоненциальная задержка — хорошая практика).
Подключения ИИ-агентов (через OAuth) ограничены отдельной квотой — числом
запросов в минуту или в месяц в зависимости от тарифа. Текущий расход показывает
GET /usage.
Что доступно на тарифе
Часть возможностей API зависит от тарифа владельца токена. Если возможность не
входит в тариф, запрос возвращает 403.
| Возможность | Когда доступна |
|---|---|
| Чтение документов и значений | на всех тарифах |
Запись значений (PUT, batchUpdate, append, clear) | на платных тарифах |
| Создание, переименование и удаление листов | на тарифе «Профессиональный» и выше |
| Вебхуки | на платных тарифах, число подписок ограничено тарифом |
Журнал действий (/audit) | на тарифе «Профессиональный» и выше |
Чтение значений
| Ограничение | Значение | Что означает |
|---|---|---|
| Размер страницы | до 1000 строк за ответ | даже без limit сервер отдаёт не больше и выставляет hasMore |
Диапазонов в batchGet | до 20 | больше — вернётся 422 |
Как листать большие диапазоны — см. Пагинация.
Вебхуки
| Ограничение | Значение |
|---|---|
| Число подписок | зависит от тарифа |
| Ячеек в одном уведомлении | до 500 (при превышении payload обрезается, а cellCount показывает полное число) |
| Коалесцирование | близкие по времени правки объединяются в одно уведомление (окно ~10 сек) |
| Попытки доставки | до 5 на одно уведомление, с нарастающей задержкой; ответ 4xx (кроме 408 и 429) считается окончательным отказом и не повторяется |
Токены и подписки
Число активных токенов и вебхуков ограничено тарифом. Значения для вашего тарифа видны в настройках аккаунта.
Рекомендации
- Читайте данные диапазонами и страницами, а не «всё сразу».
- Группируйте запись через
batchUpdateвместо множества отдельных запросов. - Обрабатывайте
429: пауза и повтор, а не немедленное повторение в цикле.