Ошибки и rate limits

Формат ошибки

Все ошибки возвращаются с ok: false:

{
  "ok": false,
  "error_code": 400,
  "description": "Bad Request: chat not found"
}

Коды ошибок

Код	Что значит	Что делать
400 Bad Request	Неверный формат параметров	Проверьте имена полей, типы
401 Unauthorized	Невалидный токен	Проверьте токен, выпустите новый
403 Forbidden	Бот заблокирован юзером, или нет прав	Перестаньте слать этому юзеру
404 Not Found	Не найден метод/чат/сообщение	Проверьте ID
409 Conflict	Уже выполнено / занято	Например, webhook уже установлен
413 Request Entity Too Large	Файл слишком большой	См. лимиты ниже
429 Too Many Requests	Rate limit	См. retry_after
500 Internal Server Error	Наша проблема	Повторить через секунду

Rate limits

На один токен бота

• 30 запросов в секунду на основной API
• 30 одновременных соединений

При превышении — HTTP 429 + retry_after секунд:

{
  "ok": false,
  "error_code": 429,
  "description": "Too Many Requests: retry after 5",
  "parameters": {"retry_after": 5}
}

На отправку сообщений

Дополнительные мягкие лимиты:

• 30 сообщений в секунду в разные чаты
• 20 сообщений в минуту в один и тот же чат
• 1 сообщение в секунду в один и тот же чат

Превышение → 429 на конкретный чат, остальные продолжают работать.

На webhook

• 40 одновременных соединений на ваш webhook (можно настроить через max_connections в setWebhook)
• 60 секунд таймаут на ответ
• Retry с экспоненциальным backoff при 5xx и таймаутах

Лимиты размеров

Что	Лимит
Сообщение (текст)	4096 символов
Caption медиа	1024 символа
Callback data	64 байта
Сторона JSON	10 МБ
Размер фото	10 МБ
Размер видео/документа	50 МБ
Webhook URL	256 символов
getMe имя	64 символа
getMe description	512 символов

Best practices

1. Бэкофф при 429

import time

def send_with_retry(method, params):
    for attempt in range(3):
        r = api.call(method, params)
        if r.get('ok'):
            return r
        if r.get('error_code') == 429:
            wait = r['parameters']['retry_after']
            time.sleep(wait)
            continue
        return r
    raise Exception('failed after 3 retries')

2. Не блокировать на сетевых вызовах

Используйте async (aiogram, grammy, async/await) или очередь сообщений.

3. Отслеживать ошибки

Подпишитесь на 403 — это юзер заблокировал бота. Удалите его из вашей рассылки.

4. Webhook idempotency

Сохраняйте update_id обработанных событий — иногда мы доставляем дубли.