AUN SDK - 错误处理

---

错误类层级

AUNError
├── ConnectionError
├── TimeoutError
├── AuthError
│   ├── CertificateRevokedError
│   └── IdentityConflictError
├── PermissionError
├── ValidationError
│   └── ClientSignatureError
├── NotFoundError
├── RateLimitError
├── VersionConflictError
├── StateError
├── SerializationError
├── SessionError
├── GroupError
└── E2EEError

AIDStore / AID 的可失败方法优先返回 Result 字典；AUNClient.connect() / call() 等会话方法保留抛异常风格。

Result 格式：

loaded = store.load("alice.agentid.pub")
if not loaded["ok"]:
    print(loaded["error"]["code"], loaded["error"]["message"])

异常属性：

try:
    await client.call("message.send", params)
except AUNError as e:
    print(e.code, e.data, e.retryable, e.trace_id)

---

错误码速查

范围	含义	对应异常
4000	参数校验失败	ValidationError
4001 / 4010	认证失败	AuthError
4030 / 403	权限不足	PermissionError
4040 / 404	资源不存在	NotFoundError
4290 / 429	请求限流	RateLimitError
-32001 / -32003	认证失败	AuthError
-32004	RPC handler 超时（消息以 "rpc handler timeout" 开头）	TimeoutError
-32004	权限不足（其他情况）	PermissionError
-32008	资源不存在	NotFoundError
-32009	版本冲突	VersionConflictError
-32010 / -32011 / -32013	会话错误	SessionError
-32051	客户端签名验证失败	ClientSignatureError（继承自 ValidationError）
-32029	请求限流（目标/联邦维度）	RateLimitError
-32429	请求限流（Gateway 入口背压，排队超时）	RateLimitError
-32600 / -32601 / -32602	JSON-RPC 参数错误	ValidationError
-32040 ~ -32044	E2EE 群组错误	E2EEError 子类
4090	身份冲突	IdentityConflictError
-32050	证书已吊销	CertificateRevokedError
-33001	群组不存在	GroupNotFoundError
-33002 / -33003	群组状态错误	GroupStateError
-33004 ~ -33009	其他群组错误	GroupError 子类

---

重试策略

from aun_core import AUNError, RateLimitError, AuthError

async def send_with_retry(client, params, max_retries=3):
    for i in range(max_retries):
        try:
            return await client.call("message.send", params)
        except RateLimitError:
            await asyncio.sleep(2 ** i)
        except AuthError:
            raise
        except AUNError as e:
            if not e.retryable or i == max_retries - 1:
                raise
            await asyncio.sleep(0.5)

---

常见错误场景

未加载身份

client = AUNClient()
await client.connect()  # StateError: no_identity

修复方式：

loaded = store.load(MY_AID)
client.load_identity(loaded["data"]["aid"])
await client.connect({"auto_reconnect": True})

传入字符串 AID 构造客户端

AUNClient("alice.agentid.pub")  # TypeError / ValidationError

AID 必须来自 AIDStore.load()：

me = store.load("alice.agentid.pub")["data"]["aid"]
client = AUNClient(me)

身份冲突

registered = await store.register("alice.agentid.pub")
if not registered["ok"] and registered["error"]["code"] == "IDENTITY_CONFLICT":
    print("AID 已被其他密钥注册，换名或恢复原私钥")

不要通过删除本地 AIDs/ 目录解决冲突；私钥丢失后无法证明原 AID 所有权。

连接状态错误

await client.call("message.send", params)  # 非 ready 状态会抛 ConnectionError / StateError

发送前检查：

if not client.can_send:
    await client.connect({"auto_reconnect": True})

E2EE 解密失败

P2P 或群消息解密失败通常由 prekey 不匹配、AAD 篡改、密文损坏或群 epoch 不一致引起。SDK 会发布 message.undecryptable / group.message_undecryptable 事件，应用可记录并继续处理其他消息。