Обработка ошибок и автоматические повторы

Какие ошибки перехватывать?

Иерархия ошибок и атрибуты

естьнетТаблицу можно прокрутить вбок

В какой класс попадает ошибка платформы?

SDK классифицирует ошибки по этим правилам; всё, что не подошло, остаётся обычным ApiError.

Как переводятся ошибки аккаунта Telegram (MTProto)?

TelegramAccount переводит исключения Telethon в ту же иерархию, поэтому один блок except работает и для бота, и для аккаунта, и для других платформ.

RateLimitError

FloodWaitError и другие ошибки Flood…; code=420, retry_after — секунды, названные Telegram. SDK сам не ждёт: решение за вами, чтобы 20-минутное ожидание не заморозило приложение.

AuthError

AuthKeyUnregisteredError, SessionRevokedError, SessionExpiredError, UserDeactivatedError, AuthKeyDuplicatedError, UnauthorizedError — сессия невалидна, аккаунт нужно переподключить (status=401).

PermissionError

ChatAdminRequiredError, ChatWriteForbiddenError, UserBannedInChannelError, ChannelPrivateError, UserPrivacyRestrictedError, MessageDeleteForbiddenError, AdminsTooMuchError, UserNotParticipantError, ChatRestrictedError (status=403).

NotFoundError

UsernameNotOccupiedError, PeerIdInvalidError, MessageIdInvalidError, ChannelInvalidError, UserIdInvalidError, InviteHashInvalidError и ValueError, который Telethon бросает, не найдя объект (status=404).

TransportError

ConnectionError, OSError, TimeoutError — связь с Telegram прервалась.

Что означают коды ошибок Meta?

Какие ошибки повторяются автоматически?

Значения RetryPolicy по умолчанию

Как передать свою RetryPolicy?

import os
from socialift import Facebook, RetryPolicy, Telegram

# Для фоновых задач: больше попыток, длиннее задержка и таймаут
patient = RetryPolicy(attempts=5, backoff_base=1.0, backoff_max=60.0)
fb = Facebook.from_env(retry=patient, timeout=60.0)

# Для операций записи, где повтор опасен: без повторов
once = RetryPolicy(attempts=1)
bot = Telegram(token=os.environ["TELEGRAM_BOT_TOKEN"], retry=once)

Рекомендуемая обработка: четыре случая

Когда повторы исчерпаны, ошибка доходит до вашего кода. Ниже — шаблон для фоновой задачи.

import logging
from socialift import ApiError, AuthError, RateLimitError, TransportError
from socialift import PermissionError as ScopeError

log = logging.getLogger("app")


async def sync_profile(ig, account, jobs):
    # account и jobs — объекты вашего приложения (запись в БД и очередь задач)
    try:
        return await ig.profile(account.token, ig_user_id=account.ig_user_id)
    except AuthError:
        account.needs_reconnect = True                 # отправьте пользователя в OAuth заново
    except ScopeError as exc:
        log.error("Не хватает разрешений: %s", exc)    # scope или App Review — повтор бесполезен
    except RateLimitError as exc:
        await jobs.retry_later(account.id, delay=exc.retry_after or 300)
    except TransportError:
        await jobs.retry_later(account.id, delay=30)
    except ApiError as exc:
        log.error("%s status=%s code=%s", exc.provider, exc.status, exc.code)

Чек-лист по обработке ошибок

• ▸Не повторяйте AuthError и PermissionError — они требуют переподключения или исправления настроек.
• ▸Если у RateLimitError нет retry_after, ставьте задачу в очередь с задержкой в минутах.
• ▸Для логов используйте str(exc), exc.status, exc.code и exc.payload. Не пишите в лог exc.url: в запросах Meta там есть query-параметр access_token.
• ▸Перехватывайте LicenseError отдельно от ApiError — это проблема лицензии, а не платформы.
• ▸ConfigurationError — ошибка в коде или переменных окружения; выявляйте её при старте.