Errors

Handling errors

Is recommended way that you should use errors inside handlers using try-except block, but in common cases you can use global errors handler at router or dispatcher level.

If you specify errors handler for router - it will be used for all handlers inside this router.

If you specify errors handler for dispatcher - it will be used for all handlers inside all routers.

@router.error(ExceptionTypeFilter(MyCustomException), F.update.message.as_("message"))
async def handle_my_custom_exception(event: ErrorEvent, message: Message):
    # do something with error
    await message.answer("Oops, something went wrong!")


@router.error()
async def error_handler(event: ErrorEvent):
    logger.critical("Critical error caused by %s", event.exception, exc_info=True)
    # do something with error
    ...

Updates that can’t be validated

An update received through a webhook (or passed to Dispatcher.feed_raw_update and Dispatcher.feed_webhook_update as a dict) that fails validation is skipped: the webhook answers it with 200 so Telegram does not redeliver it, and the update is lost. The skip is logged on aiogram.webhook with the number of validation errors (the raw update goes to the same logger at DEBUG).

When the raw update has an integer update_id, errors handlers also receive an ErrorEvent with the pydantic.ValidationError as event.exception. Its event.update carries only update_id, so every event field (event.update.message and the others) is None. An exception raised by such an errors handler is logged and does not change the answer.

from pydantic import ValidationError

@router.error(ExceptionTypeFilter(ValidationError))
async def skipped_update_handler(event: ErrorEvent):
    logger.warning("Update %d was skipped", event.update.update_id)

Network errors and the bot token

Request URLs of the Bot API contain the bot token. Network errors never contain it: TelegramNetworkError and the aiohttp errors raised by Bot.download_file() and Bot.download() show it as <bot id>:*** in their message and traceback, and keep their type, so existing except clauses still work. The original exception is available as .original and may contain the token — don’t log it.

ErrorEvent

class aiogram.types.error_event.ErrorEvent(*, update: Update, exception: Exception, **extra_data: Any)[source]

Internal event, should be used to receive errors while processing Updates from Telegram

Source: https://core.telegram.org/bots/api#error-event

update: Update

Received update

exception: Exception

Exception

Error types

exception aiogram.exceptions.AiogramError[source]

Base exception for all aiogram errors.

exception aiogram.exceptions.DetailedAiogramError(message: str)[source]

Base exception for all aiogram errors with detailed message.

exception aiogram.exceptions.CallbackAnswerException[source]

Exception for callback answer.

exception aiogram.exceptions.SceneException[source]

Exception for scenes.

exception aiogram.exceptions.UnsupportedKeywordArgument(message: str)[source]

Exception raised when a keyword argument is passed as filter.

exception aiogram.exceptions.TelegramAPIError(method: TelegramMethod, message: str)[source]

Base exception for all Telegram API errors.

exception aiogram.exceptions.TelegramNetworkError(method: TelegramMethod, message: str)[source]

Base exception for all Telegram network errors.

Its message never contains the bot token. The underlying HTTP client error is kept on original instead of being chained, because it may contain the token.

exception aiogram.exceptions.TelegramRetryAfter(method: TelegramMethod, message: str, retry_after: int)[source]

Exception raised when flood control exceeds.

exception aiogram.exceptions.TelegramMigrateToChat(method: TelegramMethod, message: str, migrate_to_chat_id: int)[source]

Exception raised when chat has been migrated to a supergroup.

exception aiogram.exceptions.TelegramBadRequest(method: TelegramMethod, message: str)[source]

Exception raised when request is malformed.

exception aiogram.exceptions.TelegramNotFound(method: TelegramMethod, message: str)[source]

Exception raised when chat, message, user, etc. not found.

exception aiogram.exceptions.TelegramConflictError(method: TelegramMethod, message: str)[source]

Exception raised when bot token is already used by another application in polling mode.

exception aiogram.exceptions.TelegramUnauthorizedError(method: TelegramMethod, message: str)[source]

Exception raised when bot token is invalid.

exception aiogram.exceptions.TelegramForbiddenError(method: TelegramMethod, message: str)[source]

Exception raised when bot is kicked from chat or etc.

exception aiogram.exceptions.TelegramServerError(method: TelegramMethod, message: str)[source]

Exception raised when Telegram server returns 5xx error.

exception aiogram.exceptions.RestartingTelegram(method: TelegramMethod, message: str)[source]

Exception raised when Telegram server is restarting.

It seems like this error is not used by Telegram anymore, but it’s still here for backward compatibility.

Currently, you should expect that Telegram can raise RetryAfter (with timeout 5 seconds)

error instead of this one.

exception aiogram.exceptions.TelegramEntityTooLarge(method: TelegramMethod, message: str)[source]

Exception raised when you are trying to send a file that is too large.

exception aiogram.exceptions.ClientDecodeError(message: str, original: Exception, data: Any)[source]

Exception raised when client can’t decode response. (Malformed response, etc.)

exception aiogram.exceptions.DataNotDictLikeError(message: str)[source]

Exception raised when data is not dict-like.