Перейти к содержанию

Исключения

AvitoError — базовый тип ошибок SDK. Специализированные исключения отражают класс сбоя: аутентификация, авторизация, validation, rate limit, transport и ошибки upstream API.

Диагностические поля

Каждое публичное исключение сохраняет безопасные диагностические данные:

Поле Назначение
operation Имя SDK-операции, во время которой возникла ошибка
status / status_code HTTP-статус upstream-ответа, если он был получен
error_code Код ошибки из тела upstream-ответа, если API его вернул
message Читаемое сообщение ошибки
details Структурированные подробности из details, fields, errors или violations
retry_after Количество секунд до повтора для 429, если есть Retry-After
request_id Идентификатор upstream-запроса, если API его вернул
attempt Номер retry-попытки, если он доступен transport-слою
method HTTP-метод запроса
endpoint Путь endpoint без OAuth-секретов и приватных headers

Секреты в payload, headers и metadata редактируются через sanitize_metadata().

Пример обработки rate limit:

from avito.core.exceptions import RateLimitError

try:
    avito.ad_stats(user_id=7).get_item_stats(item_ids=[101])
except RateLimitError as exc:
    print(exc.operation)
    print(exc.status)
    print(exc.error_code)
    print(exc.retry_after)
    print(exc.request_id)

Иерархия

Иерархия исключений SDK Avito.

AvitoError dataclass 

AvitoError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: Exception

Базовое исключение SDK с безопасными диагностическими метаданными.

status property 

status: int | None

HTTP-статус ответа API.

TransportError dataclass 

TransportError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Сбой HTTP-транспорта до получения корректного ответа API.

AuthenticationError dataclass 

AuthenticationError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Ошибка аутентификации: неверные credentials или истёкший токен (HTTP 401).

AuthorizationError dataclass 

AuthorizationError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Ошибка авторизации: недостаточно прав для операции (HTTP 403).

ValidationError dataclass 

ValidationError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

API отклонил запрос из-за некорректных параметров (HTTP 400, 422).

ConfigurationError dataclass 

ConfigurationError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

SDK сконфигурирован некорректно — ошибка обнаружена до выполнения HTTP-запроса.

RateLimitError dataclass 

RateLimitError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Превышен лимит запросов API (HTTP 429).

ConflictError dataclass 

ConflictError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Операция конфликтует с текущим состоянием upstream-ресурса (HTTP 409).

UnsupportedOperationError dataclass 

UnsupportedOperationError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Операция не поддерживается публичным Avito API или данным endpoint (HTTP 405, 501).

UpstreamApiError dataclass 

UpstreamApiError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Неизвестная ошибка upstream API вне специализированных типов SDK.

NotFoundError dataclass 

NotFoundError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: UpstreamApiError

Запрошенный ресурс не найден (HTTP 404).

ClientError dataclass 

ClientError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: UpstreamApiError

Прочая клиентская ошибка диапазона 4xx без более конкретного типа.

ServerError dataclass 

ServerError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: UpstreamApiError

Серверная ошибка диапазона 5xx.

ResponseMappingError dataclass 

ResponseMappingError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: str | None = None,
    details: object | None = None,
    retry_after: float | None = None,
    request_id: str | None = None,
    metadata: Mapping[str, object] = dict(),
    payload: object | None = None,
    headers: Mapping[str, str] | None = None,
)

Bases: AvitoError

Не удалось безопасно преобразовать ответ API в ожидаемый тип.

sanitize_metadata 

sanitize_metadata(value: object) -> object

Удаляет секреты из диагностических метаданных исключения.