Telegram Bot API: ошибки, которые мешают боту работать, и как их чинить

Обновлено: июнь 2026

Если бот перестал отвечать или сыплет ошибками, первое, что нужно понять: 90% случаев это не сбой на стороне Telegram, а проблема в коде или конфигурации. Telegram Bot API возвращает коды ошибок с понятной логикой — нужно лишь знать, что за каждым из них стоит. В этой статье разберем пять самых частых ошибок: 400 Bad Request, 401 Unauthorized, 409 Conflict, 429 Too Many Requests и SSL-проблемы. Для каждой — причина, диагностика и конкретный фикс.

TL;DR. Пять ошибок Telegram Bot API, с которыми сталкиваются вайбкодеры и разработчики в 2026 году: 400 (неверный запрос), 401 (невалидный токен), 409 (два экземпляра бота одновременно), 429 (превышен лимит запросов), SSL (проблема с сертификатом для вебхука). Каждую разбираем с примером кода и чеклистом.

Что такое Telegram Bot API и почему он возвращает ошибки?

Telegram Bot API — это HTTP-интерфейс, через который бот общается с серверами Telegram. Любой некорректный запрос получает ответ с кодом ошибки и текстовым описанием. Игнорировать эти сообщения нельзя.

Каждый ответ API выглядит так:

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

Поле error_code — это HTTP-статус. Поле description говорит, что именно пошло не так. Библиотеки вроде python-telegram-bot или aiogram оборачивают эти ответы в исключения — TelegramError, BadRequest, Unauthorized и другие. Но суть одна: смотри на код и читай описание.

Почему бот выдает ошибку 400 Bad Request?

400 Bad Request — самая частая ошибка. Значит, запрос синтаксически некорректен: неверный chat_id, неправильная разметка, пустой текст или несуществующий параметр.

Telegram строго проверяет каждый параметр запроса. Если хоть что-то не совпадает со спецификацией, вернется 400. Ошибка не означает проблему с токеном или сетью — только с данными.

Самые частые причины 400:

• chat_id не того типа. Для личных чатов это положительное число, для групп — отрицательное. Строка вместо числа — сразу 400.
• Невалидная HTML-разметка. Если используешь parse_mode="HTML", незакрытый тег (<b>текст без </b>) сломает запрос.
• Попытка отправить пустое сообщение. text="" или text=None — Telegram не принимает.
• chat not found. Пользователь не начинал диалог с ботом, или бот был заблокирован.

Вот как выглядит обработка в aiogram:

from aiogram.exceptions import TelegramBadRequest

@router.message(Command("send"))
async def send_handler(message: Message):
    try:
        await bot.send_message(
            chat_id=message.chat.id,
            text="<b>Привет</b>",
            parse_mode="HTML"
        )
    except TelegramBadRequest as e:
        logging.error(f"Bad Request: {e}")
        await message.answer("Не удалось отправить сообщение")

Диагностика простая: читай поле description в ответе. "Bad Request: message text is empty" — пустой текст. "Bad Request: can't parse entities" — проблема с разметкой. "Bad Request: chat not found" — пользователь недоступен.

Как исправить ошибку 401 Unauthorized в Telegram API?

401 Unauthorized означает одно: токен бота невалиден. Либо он был отозван через BotFather, либо скопирован с опечаткой, либо истек после смены токена.

Это серьезнее, чем 400 — бот вообще не может аутентифицироваться в API. Все запросы будут падать до тех пор, пока не появится корректный токен.

Чеклист при 401:

1. Открой BotFather в Telegram и проверь токен командой /mybots -> выбери бота -> API Token.
2. Убедись, что токен скопирован полностью. Формат: 123456789:ABCdefGhIjklMnoP-QrsTUvwXYZ.
3. Проверь, не пересоздавался ли токен. Если кто-то нажал «Revoke» в BotFather — старый токен умер мгновенно.
4. Убедись, что в коде нет лишних пробелов вокруг токена при чтении из .env.

import os
from dotenv import load_dotenv

load_dotenv()
token = os.getenv("BOT_TOKEN", "").strip()  # strip() обязателен

if not token:
    raise ValueError("BOT_TOKEN не задан в .env")

Если бот работал и внезапно перестал с 401 — первым делом проверь, не был ли токен случайно перевыпущен. Это самая частая история: кто-то из команды зашел в BotFather «посмотреть настройки» и нажал не туда.

Что делать с ошибкой 409 Conflict в Telegram боте?

409 Conflict появляется, когда два экземпляра бота одновременно пытаются получать обновления. Telegram не позволяет это — только один клиент на токен.

Эта ошибка почти всегда означает: где-то еще запущен тот же бот. На сервере осталась старая сессия, запущен дубль в другом окне терминала, или установлен вебхук при работающем polling.

Причины 409 и их фиксы:

Сценарий 1: polling + вебхук одновременно. Это несовместимо. Если использовался вебхук, перед запуском polling нужно его удалить:

await bot.delete_webhook(drop_pending_updates=True)
# Теперь запускаем polling
await dp.start_polling(bot)

Сценарий 2: два процесса polling на одном токене. Убей все старые процессы:

# Найти и остановить старые процессы бота
ps aux | grep bot.py
kill -9 <PID>

Сценарий 3: старый вебхук не удален. Проверь текущее состояние вебхука:

GET https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Если в ответе url не пустой — вебхук активен. Удали его:

GET https://api.telegram.org/bot<TOKEN>/deleteWebhook

Как справиться с ошибкой 429 Too Many Requests?

429 Too Many Requests означает превышение лимита запросов. Telegram временно блокирует бота или IP, ответ содержит поле retry_after — количество секунд, которые нужно подождать.

Telegram устанавливает несколько видов лимитов. Основные: не более 30 сообщений в секунду глобально, не более 1 сообщения в секунду в один чат. При массовых рассылках это очень легко превысить.

Правильная стратегия при 429 — exponential backoff:

import asyncio
from aiogram.exceptions import TelegramRetryAfter

async def send_with_retry(bot, chat_id, text, max_retries=5):
    for attempt in range(max_retries):
        try:
            await bot.send_message(chat_id=chat_id, text=text)
            return  # успешно
        except TelegramRetryAfter as e:
            wait_time = e.retry_after + 1  # берем из ответа API
            logging.warning(f"Rate limit. Жду {wait_time} сек. (попытка {attempt + 1})")
            await asyncio.sleep(wait_time)
    raise Exception(f"Не удалось отправить после {max_retries} попыток")

Для массовых рассылок нужна очередь с задержками:

async def broadcast(bot, user_ids: list, text: str):
    for i, user_id in enumerate(user_ids):
        try:
            await bot.send_message(chat_id=user_id, text=text)
            await asyncio.sleep(0.05)  # 50 мс между сообщениями = 20 сообщений/сек
        except TelegramRetryAfter as e:
            await asyncio.sleep(e.retry_after)
            await bot.send_message(chat_id=user_id, text=text)

Если ошибка возникает не в коде, а при обычном использовании аккаунта — подожди 15-30 минут без каких-либо действий. Повторные попытки только усугубят блокировку.

Как исправить SSL-ошибки в Telegram Bot API?

SSL-ошибки при работе с вебхуком возникают, когда сертификат сервера не проходит проверку или настроен некорректно. Telegram требует валидный SSL для всех вебхук-URL.

Вебхук работает через HTTPS — Telegram сам стучится на твой сервер. Если SSL-сертификат просрочен, самоподписанный (без загрузки в Telegram), или порт закрыт — бот не получит ни одного обновления.

Признаки SSL-проблемы:

• Вебхук установлен (в getWebhookInfo видно url), но last_error_message содержит упоминание SSL или TLS.
• Бот отвечал, потом внезапно перестал — скорее всего, истек сертификат Let's Encrypt.
• Ошибка в логах: unable to create ssl/tls secure channel или SSL: CERTIFICATE_VERIFY_FAILED.

Чеклист диагностики SSL:

Шаг 1. Проверь статус вебхука:

GET https://api.telegram.org/bot<TOKEN>/getWebhookInfo

Поле last_error_message расскажет конкретную причину.

Шаг 2. Проверь сертификат через внешний инструмент — SSL Labs (ssllabs.com) или команда openssl s_client -connect твой-домен.ru:443.

Шаг 3. Для самоподписанного сертификата нужно загрузить его при установке вебхука:

await bot.set_webhook(
    url="https://твой-домен.ru/webhook",
    certificate=open("cert.pem", "rb")
)

Шаг 4. Для серверов с устаревшим .NET или другими платформами, где TLS не подключается автоматически, явно задай протокол:

// C# / .NET
ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;
ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls13;

Проще всего использовать Let's Encrypt через Certbot — бесплатный сертификат, автоматическое обновление каждые 90 дней. Для большинства VPS это стандартное решение.

Как настроить глобальный обработчик ошибок в aiogram?

Вместо оборачивания каждого хендлера в try/except, лучше настроить один централизованный ErrorHandler — он перехватит все необработанные исключения бота.

Из транскрипции разборов по aiogram: важно использовать именно ErrorHandler, а не Messenger. И обязательно возвращать True — без него обработка работает некорректно.

# errors.py
import logging
from aiogram import Router
from aiogram.exceptions import (
    TelegramUnauthorizedError,
    TelegramBadRequest,
    TelegramRetryAfter,
    TelegramAPIError
)
from aiogram.types import Update

router = Router()

@router.errors()
async def errors_handler(update: Update, exception: Exception) -> bool:
    if isinstance(exception, TelegramUnauthorizedError):
        logging.error("Unauthorized: токен невалиден")
        return True

    if isinstance(exception, TelegramRetryAfter):
        logging.warning(f"Rate limit. Retry after: {exception.retry_after} сек.")
        return True

    if isinstance(exception, TelegramBadRequest):
        logging.error(f"Bad Request: {exception}")
        return True

    if isinstance(exception, TelegramAPIError):
        logging.exception(f"Telegram API Error: {exception}\nUpdate: {update}")
        return True

    logging.exception(f"Неизвестная ошибка: {exception}\nUpdate: {update}")
    return True

Подключи роутер в основном файле:

# main.py
from errors import router as errors_router

dp.include_router(errors_router)

Уровень логирования меняй в зависимости от среды: logging.DEBUG — при разработке, logging.INFO — в продакшене. Иначе консоль захлебнется в debug-сообщениях.

Максим: «Ребят, это работает — мы в VibeCoderz строим ботов именно так. Когда делали инфраструктуру для GoBanana, первые версии были без нормальной обработки ошибок. Потом один 429 лег всю рассылку на 80 000 подписчиков. После этого централизованный ErrorHandler и exponential backoff стали стандартом для всех наших продуктов.»

Как проверить, что Telegram API вообще работает?

Если бот не отвечает и в логах нет явных ошибок — проверь статус самой платформы. Иногда проблема не у тебя.

Telegram публикует статус на t.me/BotNews. Также можно использовать Downdetector или просто проверить через браузер:

GET https://api.telegram.org/bot<TOKEN>/getMe

Если ответ пришел с "ok": true и данными бота — API работает, проблема в твоем коде. Если таймаут или 5xx — ждешь Telegram.

FAQ по ошибкам Telegram Bot API

Почему бот перестал отвечать без каких-либо ошибок в логах? Скорее всего, процесс бота завис или упал, а supervisor/systemd его не перезапустил. Проверь, что процесс жив: ps aux | grep bot.py. Второй вариант — активный вебхук перехватывает обновления, а polling их не видит.

api telegram не работает — как понять, моя проблема или Telegram? Отправь GET-запрос на https://api.telegram.org/bot<TOKEN>/getMe. Если ответ не пришел за 5 секунд — скорее всего, сбой на стороне Telegram. Проверь t.me/BotNews и Downdetector.

Что значит api telegram exception CantParseEntities? Невалидная HTML- или Markdown-разметка в тексте сообщения. Незакрытый тег, неправильный спецсимвол или несовместимый parse_mode. Проверь текст на корректность разметки или временно убери parse_mode.

Как избежать 429 при массовой рассылке? Используй задержку 50-100 мс между сообщениями в разные чаты. Для одного чата — не чаще 1 сообщения в секунду. Реализуй retry_after из ответа 429: библиотека aiogram дает его в TelegramRetryAfter.retry_after.

Telegram api ssl — почему вебхук перестал работать? Первая проверка — getWebhookInfo, поле last_error_message. Чаще всего истек сертификат Let's Encrypt (срок 90 дней). Второй вариант — изменился IP сервера и сертификат не привязан к новому адресу. Перевыпусти сертификат и переустанови вебхук.

Можно ли использовать вебхук и polling одновременно? Нет. Это вызовет 409 Conflict. Выбери один режим. Polling проще для разработки и дебага. Вебхук лучше для продакшена — меньше нагрузки и мгновенный отклик.

Бот работал, после деплоя перестал — что проверить первым? По порядку: 1) токен в переменных окружения нового сервера, 2) наличие старого запущенного экземпляра (409), 3) статус вебхука если был переезд на новый домен, 4) сетевые правила файрвола (порт 443 для вебхука).

Глоссарий

Telegram Bot API — HTTP-интерфейс для управления ботами Telegram. Документация: core.telegram.org/bots/api.

BotFather — официальный бот Telegram для создания и настройки ботов. Через него выдается и отзывается токен.

Токен бота — уникальный ключ доступа к API формата 123456789:ABCdef.... Не публиковать и не передавать третьим лицам.

Webhook (вебхук) — режим работы, при котором Telegram сам отправляет обновления на указанный HTTPS-URL сервера.

Polling (поллинг) — режим работы, при котором бот сам регулярно запрашивает обновления у Telegram API.

Rate limit — ограничение частоты запросов. Telegram: 30 сообщений/сек глобально, 1 сообщение/сек в один чат.

SSL/TLS — протоколы шифрования соединения. Telegram требует валидный SSL для вебхуков.

aiogram — популярная асинхронная Python-библиотека для работы с Telegram Bot API.

ErrorHandler — централизованный обработчик исключений в aiogram, перехватывает все необработанные ошибки.

exponential backoff — стратегия повторных попыток с увеличивающимися интервалами ожидания.

Что дальше

Если разбираешься с ботами для своих продуктов или учишься создавать их с нуля — загляни в каталог AI-инструментов. Там собраны IDE и инструменты, которые ускоряют разработку: от Cursor до Claude Code.

Если нужна помощь с архитектурой бота или хочешь разобраться, как выстроить процесс без лишних ошибок с самого начала — запишись на консультацию к Максиму.

Обновлено: июнь 2026. Актуально для Telegram Bot API и aiogram 3.x.