跳转至

异常体系

bt_api_py 使用统一的自定义异常体系，所有异常均继承自 BtApiError。

异常层次结构

BtApiError
├── ExchangeNotFoundError       # 交易所未注册或未添加
├── ExchangeConnectionError     # 连接失败
│   └── AuthenticationError    # 认证失败
├── RequestTimeoutError         # 请求超时
├── RequestError                # 请求失败（非超时）
│   └── RequestFailedError     # HTTP 请求失败
├── OrderError                  # 下单/撤单失败
│   ├── InsufficientBalanceError # 余额不足
│   ├── InvalidOrderError       # 订单参数无效
│   └── OrderNotFoundError      # 订单不存在
├── SubscribeError              # 订阅失败
├── DataParseError              # 数据解析失败
├── RateLimitError              # 速率限制
├── NetworkError                # 网络错误
├── InvalidSymbolError          # 无效交易对
├── ConfigurationError          # 配置错误
└── WebSocketError              # WebSocket 错误

使用示例

from bt_api_py.exceptions import (
    BtApiError,
    ExchangeNotFoundError,
    RateLimitError,
    RequestTimeoutError,
)

try:
    ticker = api.get_tick("UNKNOWN___SPOT", "BTCUSDT")
except ExchangeNotFoundError as e:
    print(f"交易所未找到: {e}")
except RateLimitError as e:
    print(f"频率限制，{e.retry_after}s 后重试")
except RequestTimeoutError as e:
    print(f"请求超时: {e}")
except BtApiError as e:
    print(f"其他错误: {e}")

bt_api_py 自定义异常体系 统一各模块的异常处理，替代散乱的 assert / raise Exception / ConnectionError

ExchangeConnectionAlias module-attribute 

ExchangeConnectionAlias = ExchangeConnectionError

BtApiError

Bases: Exception

bt_api_py 所有异常的基类

ExchangeNotFoundError 

ExchangeNotFoundError(exchange_name: str, available: str | list[str] | None = None)

Bases: BtApiError

交易所未注册或未添加

exchange_name instance-attribute 

exchange_name = exchange_name

available instance-attribute 

available = available

ExchangeConnectionError 

ExchangeConnectionError(exchange_name: str, detail: str = '')

Bases: BtApiError

交易所连接失败

exchange_name instance-attribute 

exchange_name = exchange_name

AuthenticationError 

AuthenticationError(exchange_name: str, detail: str = '')

Bases: ExchangeConnectionError

认证失败（API Key / 密码 / 穿透式认证错误）

RequestTimeoutError 

RequestTimeoutError(exchange_name: str, url: str = '', timeout: int | float = 0)

Bases: BtApiError

REST / 查询请求超时

exchange_name instance-attribute 

exchange_name = exchange_name

url instance-attribute 

url = url

timeout instance-attribute 

timeout = timeout

RequestError 

RequestError(exchange_name: str, url: str = '', detail: str = '')

Bases: BtApiError

REST 请求失败（非超时）

exchange_name instance-attribute 

exchange_name = exchange_name

OrderError 

OrderError(exchange_name: str, symbol: str = '', detail: str = '')

Bases: BtApiError

下单 / 撤单操作失败

exchange_name instance-attribute 

exchange_name = exchange_name

symbol instance-attribute 

symbol = symbol

SubscribeError 

SubscribeError(exchange_name: str, detail: str = '')

Bases: BtApiError

订阅失败

exchange_name instance-attribute 

exchange_name = exchange_name

DataParseError 

DataParseError(container_class: str = '', detail: str = '')

Bases: BtApiError

数据解析失败

container_class instance-attribute 

container_class = container_class

detail instance-attribute 

detail = detail

RateLimitError 

RateLimitError(exchange_name: str, retry_after: int | float | None = None, detail: str = '')

Bases: BtApiError

API 速率限制错误

exchange_name instance-attribute 

exchange_name = exchange_name

retry_after instance-attribute 

retry_after = retry_after

NetworkError 

NetworkError(exchange_name: str, detail: str = '')

Bases: BtApiError

网络错误（连接失败、DNS 解析失败等）

exchange_name instance-attribute 

exchange_name = exchange_name

InvalidSymbolError 

InvalidSymbolError(exchange_name: str, symbol: str, detail: str = '')

Bases: BtApiError

无效的交易对符号

exchange_name instance-attribute 

exchange_name = exchange_name

symbol instance-attribute 

symbol = symbol

InsufficientBalanceError 

InsufficientBalanceError(exchange_name: str, symbol: str = '', required: float | None = None, available: float | None = None)

Bases: OrderError

余额不足

required instance-attribute 

required = required

available instance-attribute 

available = available

InvalidOrderError 

InvalidOrderError(exchange_name: str, symbol: str = '', detail: str = '')

Bases: OrderError

无效的订单参数（价格、数量等）

OrderNotFoundError 

OrderNotFoundError(exchange_name: str, order_id: str, symbol: str = '')

Bases: OrderError

订单不存在

order_id instance-attribute 

order_id = order_id

ConfigurationError 

ConfigurationError(detail: str = '')

Bases: BtApiError

配置错误（缺少必需参数、配置格式错误等）

detail instance-attribute 

detail = detail

WebSocketError 

WebSocketError(exchange_name: str, detail: str = '')

Bases: BtApiError

WebSocket 连接或订阅错误

exchange_name instance-attribute 

exchange_name = exchange_name

CurrencyNotFoundError 

CurrencyNotFoundError(exchange_name: str, currency: str)

Bases: BtApiError

Currency not found in exchange account.

exchange_name instance-attribute 

exchange_name = exchange_name

currency instance-attribute 

currency = currency

QueueNotInitializedError 

QueueNotInitializedError(queue_name: str = '', detail: str = '')

Bases: DataParseError

Raised when data_queue is not initialized before data parsing.

queue_name instance-attribute 

queue_name = queue_name

RequestFailedError 

RequestFailedError(exchange_name: str | None = None, url: str = '', detail: str = '', *, venue: str = '', message: str = '', status_code: int | None = None)

Bases: RequestError

通用请求失败错误（用于 HTTP 客户端）

venue instance-attribute 

venue = name

status_code instance-attribute 

status_code = status_code

is_network_error 

is_network_error(error: Exception) -> bool

Check if error is network-related (connection, timeout, etc.).

is_auth_error 

is_auth_error(error: Exception) -> bool

Check if error is authentication-related.

is_rate_limit_error 

is_rate_limit_error(error: Exception) -> bool

Check if error is rate-limit-related.

is_order_error 

is_order_error(error: Exception) -> bool

Check if error is order-related (insufficient balance, invalid order, etc.).

is_user_recoverable 

is_user_recoverable(error: Exception) -> bool

Check if error can be recovered by user action (e.g., fix params, retry later).