错误处理

失败时抛 DarraError 子类（code / message / hint）。hint 文案与 错误码目录 逐字一致，绑定原样透传，可原样展示给最终用户。native 找不到或 ABI 主版本不是 1 时抛 DarraLoadError（code 为 None）。

Python 把 C 的线程局部错误槽翻译成异常：调用方不必自己调 darra_last_error。参数契约违反（空路径 / 裸缓冲缺宽高 / 已关闭会话）属调用方 bug，抛 InternalError（码 18），message 指明哪个参数。SDK 在任何非法入参下都不崩溃。

exception_for_code(code, message, hint="") 按码构造对应子类；未知新码兜底为 DarraError 基类，code 原样保留。

异常层次

类别	属性	类型	访问	说明
基类	DarraError	Exception	抛出	全部 Darra AI SDK 错误的基类。绑定侧错误 code 为 None
	DarraError.code	int | None	只读	darra_error_code 整数值
	DarraError.message	str	只读	错误描述（UTF-8）
	DarraError.hint	str	只读	修复建议，可为空串
	DarraLoadError	DarraError	抛出	native 加载失败或 ABI 不匹配。code 恒为 None
IO / 容器	IoNotFoundError	DarraError	抛出	码 1：文件不存在（容器 / 授权 / 图片 / 离线包路径错）
	IoDeniedError	DarraError	抛出	码 2：文件存在但读写被拒
	BadContainerError	DarraError	抛出	码 3：.darmodel 损坏 / 非 DARM1 / 被截断篡改
	BadLicenseError	DarraError	抛出	码 4：.darmkey 损坏或与容器不配对
授权	PasswordRequiredError	DarraError	抛出	码 5：需要密码但没给
	PasswordWrongError	DarraError	抛出	码 6：密码错误
	MachineMismatchError	DarraError	抛出	码 7：绑机授权用在非目标机器
	TrialExhaustedError	DarraError	抛出	码 8：试用计次已用完
平台 / Provider	UnsupportedPayloadError	DarraError	抛出	码 9：载荷类型当前平台/Provider 不支持（含 Windows 上 rknn 载荷）
	UnsupportedPlatformError	DarraError	抛出	码 10：OS/架构不在支持矩阵（含 Windows 上指名 edge-rknn）
	ProviderMissingError	DarraError	抛出	码 11：运行时 Provider 包未安装
	ProviderAbiMismatchError	DarraError	抛出	码 12：Provider 包与 Core ABI 不匹配
	HardwareMissingError	DarraError	抛出	码 13：未探测到所需硬件
	DriverTooOldError	DarraError	抛出	码 14：驱动版本低于 Provider 要求（SDK 不代装）
下载 / 取消 / 内部	NetworkFailedError	DarraError	抛出	码 15：清单 / 运行时包下载失败
	ChecksumMismatchError	DarraError	抛出	码 16：下载包或离线包 sha256 校验不过
	CancelledError	DarraError	抛出	码 17：ensure 被取消
	InternalError	DarraError	抛出	码 18：SDK 内部错误；也用于调用方参数契约违反

str(ex) 格式：[码] 描述 | 建议: hint。绑定侧错误（DarraLoadError）头为 [darra-ai]。

基类

DarraError

class DarraError(Exception):
    CODE: int | None = None
    def __init__(self, code: int | None, message: str, hint: str = "") -> None

全部 Darra AI SDK 错误的基类。

相关属性:

• code (int | None) — darra_error_code 整数值；绑定侧错误为 None
• message (str) — 错误描述（UTF-8）
• hint (str) — 修复建议，可为空串

DarraLoadError

class DarraLoadError(DarraError):
    def __init__(self, message: str, hint: str = "") -> None

native 内核（DarraAI.Core）加载失败或 ABI 不匹配。属绑定侧错误，code 恒为 None。

备注

典型原因：包内 / DARRA_AI_CORE_PATH / 系统路径都找不到 native；找到了但 dlopen 失败（位数、缺依赖）；ABI major ≠ 1。message 带全部尝试过的路径。处理：安装官方 wheel（pip install darra-ai），或设 DARRA_AI_CORE_PATH，或把库放进系统搜索路径。

exception_for_code()

def exception_for_code(code: int, message: str, hint: str = "") -> DarraError

按错误码构造对应子类实例；未知码（新 dll 追加）兜底为 DarraError 基类。

参数:

• code (int) — darra_error_code
• message (str) — 错误描述
• hint (str) — 修复建议，默认空串

返回值:

• DarraError — 对应子类或基类

Windows 无 RKNN

场景	异常	码
Windows 收到 rknn 载荷	UnsupportedPayloadError	9
Windows 上指名 edge-rknn	UnsupportedPlatformError	10
macOS / 32 位	DarraLoadError 或 UnsupportedPlatformError	None / 10

逐码 hint 原文见 错误码，Python 不改写。

完整示例

from darra_ai import Session, DarraError
from darra_ai.errors import IoNotFoundError, UnsupportedPayloadError

try:
    with Session.open("model.darmodel", key_path="model.darmkey") as s:
        s.infer_image(jpg)
except IoNotFoundError as ex:
    print("文件不存在:", ex.hint)
except UnsupportedPayloadError as ex:
    # Windows 上 rknn 载荷走这里
    print(ex)
except DarraError as ex:
    print(ex)  # [码] 描述 | 建议: hint

只捕获基类即可覆盖全部业务错误。需要按码分支时用子类，或读 ex.code。