错误码

失败时取本线程 darra_last_error，再抛对应子类。Message 格式为 [码] 描述 | 建议: hint。Hint 原文透传，不改写，可原样展示给最终用户。

错误码用枚举 AiErrorCode，与 darra_error_code 逐码对应。每个非 0 码一个异常子类；未知新码兜底为 AiException 基类，Code 原样保留。

提示

完整 hint 文案见 错误码。公开 runtime 物理上没有加密 / 签发符号。

捕获

try
{
    using var session = AiSession.Open("model.darmodel", keyPath: "model.darmkey");
}
catch (AiException ex)
{
    Console.Error.WriteLine(ex.Message);
    Console.Error.WriteLine(ex.Hint);
    if (ex.Code is int c)
        Console.Error.WriteLine((AiErrorCode)c);
}

优先 catch 子类（AiProviderMissingException 等）；需要按码分支时把 Code 转成 AiErrorCode。绑定侧加载 / ABI / authoring 缺符号时 Code 为 null，没有对应 darra_error_code。

基类属性

类别	属性	类型	访问	说明
AiException	Code	int?	只读	darra_error_code 整数值；绑定侧加载 / ABI / authoring 缺符号为 null
	Hint	string	只读	修复建议（error-catalog 标准文案，可为空串）

AiErrorCode

值	名称	说明
0	Ok	成功，不抛异常
1	IoNotFound	文件不存在（容器 / 授权 / 图片 / 离线包路径错）
2	IoDenied	文件存在但读 / 写被拒
3	BadContainer	.darmodel 损坏 / 非 DARM1 / 被截断篡改
4	BadLicense	.darmkey 损坏或与容器不配对
5	PasswordRequired	该容器需要密码但调用方没给
6	PasswordWrong	密码错误
7	MachineMismatch	绑机授权在非目标机器上使用
8	TrialExhausted	试用计次已用完
9	UnsupportedPayload	载荷类型在当前平台 / Provider 下不支持（含 Windows 上的 rknn、.pt / .pth）
10	UnsupportedPlatform	整个 OS / 架构不在支持矩阵（含 Windows 上指名 edge-rknn）
11	ProviderMissing	需要的运行时 Provider 包未安装
12	ProviderAbiMismatch	Provider 包与内核 ABI 不匹配
13	HardwareMissing	未探测到所需硬件
14	DriverTooOld	驱动版本低于 Provider 包要求（SDK 不代装）
15	NetworkFailed	清单 / 运行时包下载失败
16	ChecksumMismatch	下载包或离线包 sha256 校验不过
17	Cancelled	操作被取消（AiRuntime.Cancel）
18	Internal	SDK 内部错误；也用于调用方参数契约违反

public enum AiErrorCode
{
    Ok                   = 0,
    IoNotFound           = 1,
    IoDenied             = 2,
    BadContainer         = 3,
    BadLicense           = 4,
    PasswordRequired     = 5,
    PasswordWrong        = 6,
    MachineMismatch      = 7,
    TrialExhausted       = 8,
    UnsupportedPayload   = 9,
    UnsupportedPlatform  = 10,
    ProviderMissing      = 11,
    ProviderAbiMismatch  = 12,
    HardwareMissing      = 13,
    DriverTooOld         = 14,
    NetworkFailed        = 15,
    ChecksumMismatch     = 16,
    Cancelled            = 17,
    Internal             = 18,
}

异常子类

类别	属性	类型	访问	说明
绑定侧（Code = null）	AiLoadException	AiException	抛出	native 内核加载失败或 ABI 不匹配。Code 恒为 null
	AiAuthoringUnavailableException	AiException	抛出	runtime 构建没有 authoring 符号。文案固定：当前 SDK 为 runtime 构建，不含加密/签发能力
IO / 容器	AiIoNotFoundException	AiException	抛出	IoNotFound (1)：文件不存在（容器 / 授权 / 图片 / 离线包路径错）
	AiIoDeniedException	AiException	抛出	IoDenied (2)：文件存在但读 / 写被拒
	AiBadContainerException	AiException	抛出	BadContainer (3)：.darmodel 损坏 / 非 DARM1 / 被截断篡改
授权（消费已签发容器）	AiBadLicenseException	AiException	抛出	BadLicense (4)：.darmkey 损坏或与容器不配对
	AiPasswordRequiredException	AiException	抛出	PasswordRequired (5)：该容器需要密码但调用方没给
	AiPasswordWrongException	AiException	抛出	PasswordWrong (6)：密码错误
	AiMachineMismatchException	AiException	抛出	MachineMismatch (7)：绑机授权在非目标机器上使用
	AiTrialExhaustedException	AiException	抛出	TrialExhausted (8)：试用计次已用完
平台 / Provider	AiUnsupportedPayloadException	AiException	抛出	UnsupportedPayload (9)：载荷类型在当前平台 / Provider 下不支持（含 Windows 上的 rknn、.pt / .pth）
	AiUnsupportedPlatformException	AiException	抛出	UnsupportedPlatform (10)：整个 OS / 架构不在支持矩阵（含 Windows 上指名 edge-rknn）
	AiProviderMissingException	AiException	抛出	ProviderMissing (11)：需要的运行时 Provider 包未安装
	AiProviderAbiMismatchException	AiException	抛出	ProviderAbiMismatch (12)：Provider 包与内核 ABI 不匹配
	AiHardwareMissingException	AiException	抛出	HardwareMissing (13)：未探测到所需硬件
	AiDriverTooOldException	AiException	抛出	DriverTooOld (14)：驱动版本低于 Provider 包要求（SDK 不代装）
安装 / 内部	AiNetworkFailedException	AiException	抛出	NetworkFailed (15)：清单 / 运行时包下载失败
	AiChecksumMismatchException	AiException	抛出	ChecksumMismatch (16)：下载包或离线包 sha256 校验不过
	AiCancelledException	AiException	抛出	Cancelled (17)：操作被取消（AiRuntime.Cancel）
	AiInternalException	AiException	抛出	Internal (18)：SDK 内部错误；也用于调用方参数契约违反

AiException

public class AiException : Exception
{
    public int? Code { get; }
    public string Hint { get; }
}

全部 Darra AI SDK 错误的基类。Hint 来自线程局部错误槽，可原样展示给最终用户。

AiLoadException

public sealed class AiLoadException : AiException

native 内核加载失败或 ABI 不匹配。Code 恒为 null。

AiAuthoringUnavailableException

public sealed class AiAuthoringUnavailableException : AiException

runtime 构建没有 authoring 符号。文案固定：「当前 SDK 为 runtime 构建，不含加密/签发能力」。公开 runtime 物理上没有 darra_encrypt_ / darra_issue_ / darra_fingerprint_perturb 符号。