Коды ошибок
API возвращает стандартные HTTP-коды с JSON-телом ошибки. Поле retryable указывает, стоит ли повторить запрос.
Формат ошибки:
400 — Невалидный запрос (отсутствуют обязательные поля, неверный формат)
401 — Неверный или отсутствующий API-ключ
403 — Нет доступа к ресурсу
404 — Подписчик или ресурс не найден
409 — Конфликт (например, OTP уже отправлен)
422 — Ошибка валидации (текст слишком длинный, невалидный URL)
429 — Превышен rate limit (retryable: true, заголовок Retry-After)
500 — Внутренняя ошибка сервера (retryable: true)
Лимиты
Rate limits и ограничения на размеры полей.
Rate limit: 300 запросов/мин на проект. При превышении — 429 Too Many Requests.
Текст сообщения: до 4 096 символов.
Кнопки: до 3 рядов, до 3 кнопок в ряду.
Медиа: до 20 МБ (photo), 50 МБ (video/document).
Broadcast: до 100 000 подписчиков за одну рассылку.
OTP: TTL 5 мин, макс. 5 попыток, 1 активный код на subscriber_id.
Теги: до 20 тегов на проект, длина тега до 64 символов.
Разрешения: до 20 на проект.
Шаблоны: до 100 на проект.
Заголовки X-RateLimit-* не возвращаются. При превышении лимита API возвращает только HTTP 429 с телом ошибки. Рекомендуем реализовать экспоненциальный backoff на своей стороне.
Обработка ошибок и retry
Рекомендации по обработке ошибок API и стратегии повторных запросов.
retryable: true — ошибку можно повторить (429, 500). Используйте exponential backoff: 1с → 2с → 4с, максимум 3 попытки.
retryable: false — повторять бессмысленно (400, 401, 403, 404, 409). Исправьте запрос перед повторной отправкой.
Retry-After — при 429 заголовок указывает сколько секунд ждать перед повторным запросом. Rate limit: 300 запросов в минуту на проект.
Exponential backoff — увеличивайте задержку между попытками: 1с, 2с, 4с. Не повторяйте POST-запросы (send, broadcast) автоматически — используйте поле retryable для принятия решения.