Telegram Bot API: все коды ошибок, их описание и способы исправления

Работа с Telegram Bot API часто сопровождается ошибками, которые могут нарушить функциональность бота. В этом руководстве мы разберем основные коды ошибок, их причины и способы устранения. Информация актуальна на 2025 год и основана на официальной документации и опыте разработчиков.

Ошибки 4xx: проблемы на стороне клиента

400 Bad Request

Описание: Некорректный запрос. Чаще всего возникает из-за ошибок в структуре запроса, неверных параметров или формата данных.

Возможные причины:

• Неправильный chat_id.

• Пустое текстовое сообщение (text не указан).

• Некорректный JSON в клавиатуре (например, ошибка в reply_markup).

Как исправить:

• Проверьте обязательные параметры (например, chat_id, text).

• Используйте валидаторы JSON для проверки структуры данных.

• Убедитесь, что файлы (например, photo, video) передаются корректно.

401 Unauthorized

Описание: Ошибка авторизации. Возникает при неверном токене бота или отсутствии прав доступа.
Как исправить:

• Проверьте корректность токена бота в запросе (URL вида https://api.telegram.org/bot<token>/method).

• Обновите токен, если он был скомпрометирован.

403 Forbidden

Описание: Доступ к ресурсу запрещен.
Возможные причины:

• Бот заблокирован пользователем (bot blocked by user).

• Попытка отправить сообщение другому боту (bot can't send messages to bots).

• Пользователь деактивирован (user is deactivated).

Как исправить:

• Убедитесь, что бот не заблокирован в чате.

• Проверьте chat_id и права доступа.

404 Not Found

Описание: Ресурс не найден.
Возможные причины:

• Неверный chat_id или message_id.

• Устаревший метод API (например, после обновления Bot API).

Как исправить:

• Обновите chat_id (например, после миграции группы в супергруппу).

• Проверьте актуальность используемых методов в документации.

429 Too Many Requests

Описание: Превышен лимит запросов. Telegram ограничивает количество запросов от бота в секунду (например, 30 сообщений в секунду).
Как исправить:

• Добавьте задержку между запросами (используйте параметр retry_after из ответа).

• Внедрите очередь сообщений с ограничением скорости (например, через time.sleep()).

2. Ошибки 5xx: проблемы на стороне сервера

500 Internal Server Error

Описание: Внутренняя ошибка сервера Telegram.
Причины: Сбои в работе серверов Telegram или временная недоступность API.
Как исправить:

• Повторите запрос через 1–2 минуты.

• Если ошибка сохраняется, сообщите в поддержку Telegram.

502 Bad Gateway

Описание: Ошибка прокси-сервера.
Причины: Проблемы с сетевым соединением между вашим сервером и Telegram.
Как исправить:

• Проверьте настройки прокси или VPN.

• Убедитесь, что ваш сервер имеет стабильное интернет-соединение.

3. Специфичные ошибки Telegram Bot API

409 Conflict

Описание: Конфликт данных. Например, попытка изменить сообщение, которое уже было отредактировано.
Как исправить:

• Проверьте актуальность данных перед изменением.

• Используйте version или timestamp для контроля изменений.

420 Flood Wait

Описание: Превышение лимита запросов для конкретного метода.
Пример: FLOOD_WAIT_X — требуется подождать X секунд.
Как исправить:

• Внедрите обработку ошибки с автоматической паузой на время retry_after.

303 See Other

Описание: Требуется перенаправление запроса в другой дата-центр.
Примеры:

• FILE_MIGRATE_X — файл хранится в другом дата-центре.

• USER_MIGRATE_X — пользователь привязан к другому дата-центру.

Как исправить:

• Повторите запрос, указав в URL номер дата-центра из ошибки (например, dc=X).

Общие рекомендации по обработке ошибок

1. Логируйте ошибки: Записывайте коды, описания и контекст запросов для анализа.

2. Используйте retry-механизмы: Для ошибок 429, 500, 502 добавляйте повторы с экспоненциальной задержкой.

3. Проверяйте документацию: Telegram Bot API часто обновляется — актуальные методы и параметры см. здесь.

4. Тестируйте в sandbox: Перед запуском в продакшн проверяйте бота в тестовой среде.

Совет: Для сложных случаев (например, ошибка AUTH_KEY_DUPLICATED) пересоздайте сессию авторизации. Если проблема не решается, обратитесь в поддержку Telegram.