跳转至

Exception API

Exception Hierarchy

Exception
└─ BaseError
   ├─ ApiError
   │  ├─ ApiDataError
   │  ├─ CredentialError
   │  │  ├─ LoginExpiredError
   │  │  └─ NotLoginError
   │  ├─ RequestGroupResultMissingError
   │  ├─ SignInvalidError
   │  └─ RatelimitedError
   ├─ HTTPError
   ├─ LoginError
   └─ NetworkError

qqmusic_api.core.exceptions

统一异常定义模块.

BaseError 

BaseError(
    message: str,
    context: dict[str, Any] | None = None,
    cause: BaseException | None = None,
)

Bases: Exception

本库所有自定义异常的基类.

ATTRIBUTE DESCRIPTION
message

错误描述信息.

TYPE: str

context

错误相关的上下文数据.

TYPE: dict[str, Any]

cause

导致此异常的原始异常(如果有).

TYPE: BaseException | None

Source code in qqmusic_api/core/exceptions.py 
32
33
34
35
36
37
38
39
40
41
def __init__(
    self,
    message: str,
    context: dict[str, Any] | None = None,
    cause: BaseException | None = None,
):
    super().__init__(message)
    self.message = message
    self.context = context or {}
    self.cause = cause

NetworkError 

NetworkError(
    message: str, original_exc: Exception | None = None
)

Bases: BaseError

网络连接失败异常 (如 DNS 解析失败、连接超时、连接被拒绝).

ATTRIBUTE DESCRIPTION
message

错误描述信息.

TYPE: str

original_exc

原始的网络异常对象.

TYPE: Exception | None

Source code in qqmusic_api/core/exceptions.py 
56
57
58
def __init__(self, message: str, original_exc: Exception | None = None):
    super().__init__(message, cause=original_exc)
    self.original_exc = original_exc

HTTPError 

HTTPError(
    message: str,
    status_code: int,
    cause: BaseException | None = None,
)

Bases: BaseError

HTTP 协议错误 (状态码非 200).

ATTRIBUTE DESCRIPTION
message

错误描述信息.

TYPE: str

status_code

HTTP 响应状态码.

TYPE: int

Source code in qqmusic_api/core/exceptions.py 
69
70
71
def __init__(self, message: str, status_code: int, cause: BaseException | None = None):
    super().__init__(f"HTTP {status_code}: {message}", context={"status_code": status_code}, cause=cause)
    self.status_code = status_code

ApiError 

ApiError(
    message: str,
    code: int = -1,
    data: Any = None,
    cause: BaseException | None = None,
    context: dict[str, Any] | None = None,
)

Bases: BaseError

API 业务逻辑异常.

当 QQ 音乐 API 返回的 JSON 中包含非 0 的 code 时抛出。

ATTRIBUTE DESCRIPTION
message

错误描述信息.

TYPE: str

code

API 返回的错误码.

TYPE: int

data

API 返回的原始数据或相关数据.

TYPE: Any

Source code in qqmusic_api/core/exceptions.py 
85
86
87
88
89
90
91
92
93
94
95
96
97
def __init__(
    self,
    message: str,
    code: int = -1,
    data: Any = None,
    cause: BaseException | None = None,
    context: dict[str, Any] | None = None,
):
    merged_context = dict(context or {})
    merged_context.setdefault("data", data)
    super().__init__(message, context=merged_context, cause=cause)
    self.code = code
    self.data = data

ApiDataError 

ApiDataError(message: str, data: Any = None)

Bases: ApiError

API 请求成功但数据错误异常.

通常在 JSON 解析失败、关键字段缺失或数据校验失败时抛出。

Source code in qqmusic_api/core/exceptions.py 
130
131
132
133
def __init__(self, message: str, data: Any = None):
    payload = data if data is not None else {}
    full_msg = f"API Data Error: {message}"
    super().__init__(full_msg, code=-2, data=payload)

CredentialError 

CredentialError(
    message: str,
    code: int = -1,
    data: Any = None,
    cause: BaseException | None = None,
    context: dict[str, Any] | None = None,
)

Bases: ApiError

凭证相关错误的基类异常.

所有与 Cookie、Token、登录态相关的异常都应继承此类。

Source code in qqmusic_api/core/exceptions.py 
85
86
87
88
89
90
91
92
93
94
95
96
97
def __init__(
    self,
    message: str,
    code: int = -1,
    data: Any = None,
    cause: BaseException | None = None,
    context: dict[str, Any] | None = None,
):
    merged_context = dict(context or {})
    merged_context.setdefault("data", data)
    super().__init__(message, context=merged_context, cause=cause)
    self.code = code
    self.data = data

LoginExpiredError 

LoginExpiredError(
    message: str = "登录凭证已过期, 请重新登录",
    data: dict | None = None,
)

Bases: CredentialError

登录凭证过期异常 (code=1000,104400,104401).

当 API 返回 1000, 104400, 104401 错误码时抛出,提示用户需要重新登录或刷新 Cookie。

Source code in qqmusic_api/core/exceptions.py 
149
150
def __init__(self, message: str = "登录凭证已过期, 请重新登录", data: dict | None = None):
    super().__init__(message, code=1000, data=data)

NotLoginError 

NotLoginError(
    message: str = "未检测到有效登录信息",
    data: dict | None = None,
)

Bases: CredentialError

未登录异常.

当本地未检测到有效 Cookie 或 Credential 为空时抛出。

Source code in qqmusic_api/core/exceptions.py 
159
160
def __init__(self, message: str = "未检测到有效登录信息", data: dict | None = None):
    super().__init__(message, code=-1, data=data)

LoginError 

LoginError(
    message: str = "登录失败",
    cause: BaseException | None = None,
)

Bases: BaseError

登录操作失败异常.

通常在扫码登录流程中断、超时或网络失败时抛出。

Source code in qqmusic_api/core/exceptions.py 
169
170
def __init__(self, message: str = "登录失败", cause: BaseException | None = None):
    super().__init__(message, cause=cause)

RequestGroupResultMissingError 

RequestGroupResultMissingError(
    message: str, context: dict[str, Any] | None = None
)

Bases: ApiError

RequestGroup 结果缺失异常.

当批量请求执行完成后, 某个索引位置未被任何批次写回时抛出。

Source code in qqmusic_api/core/exceptions.py 
179
180
def __init__(self, message: str, context: dict[str, Any] | None = None):
    super().__init__(message, code=-1, context=context)

SignInvalidError 

SignInvalidError(
    message: str = "请求签名无效", data: dict | None = None
)

Bases: ApiError

请求签名无效异常 (code=2000).

当 API 返回 2000 错误码时抛出,通常是因为 sign 计算错误或时间戳差异过大。

Source code in qqmusic_api/core/exceptions.py 
189
190
def __init__(self, message: str = "请求签名无效", data: dict | None = None):
    super().__init__(message, code=2000, data=data)

RatelimitedError 

RatelimitedError(
    message: str = "触发风控, 需进行登录或者安全验证",
    data: dict | None = None,
)

Bases: ApiError

触发风控异常 (code=2001).

当 API 返回 2001 错误码时抛出,表示触发风控,部分接口表示 musickey 失效。

Source code in qqmusic_api/core/exceptions.py 
199
200
201
def __init__(self, message: str = "触发风控, 需进行登录或者安全验证", data: dict | None = None):
    super().__init__(message, code=2001, data=data)
    self.feedback_url = data.get("feedbackURL") if isinstance(data, dict) else None