Исключения

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

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

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

Поле	Назначение
operation	Имя SDK-операции, во время которой возникла ошибка
status / status_code	HTTP-статус upstream-ответа, если он был получен
request_id	Идентификатор upstream-запроса, если API его вернул
attempt	Номер retry-попытки, если он доступен transport-слою
method	HTTP-метод запроса
endpoint	Путь endpoint без OAuth-секретов и приватных headers

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

Иерархия

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

AvitoError dataclass

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

Bases: Exception

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

TransportError dataclass

TransportError(
    message: str,
    status_code: int | None = None,
    error_code: str | None = None,
    operation: 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,
    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,
    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,
    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,
    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,
    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,
    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,
    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,
    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,
    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,
    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,
    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,
    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

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