# 7. 错误码与状态机

## 7.1 错误码分层

### 7.1.1 JSON-RPC 2.0 通用错误码

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32700 | Parse error | 检查请求格式 |
| -32600 | Invalid Request | 检查请求格式 |
| -32601 | Method not found | 检查方法名 |
| -32602 | Invalid params | 检查参数 |
| -32603 | Internal error | 重试或报告 |

### 7.1.2 AUN 协议级错误码（认证与权限）

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32001 | Authentication failed（认证失败） | 检查凭据，重新登录 |
| -32002 | Certificate/Nonce invalid（凭据无效） | 检查证书链或 nonce |
| -32003 | Signature verification failed（签名验证失败） | 检查私钥，不重试 |
| -32004 | Permission denied（权限拒绝） | 提示用户，不重试 |
| -32005 | Authentication expired（Token 过期） | 刷新 token 或重新登录 |

### 7.1.3 AUN 协议级错误码（连接与会话）

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32010 | Agent not online | 稍后重试 |
| -32011 | Session not found | 重新连接 |
| -32013 | Initialization required | 先调用 auth.connect |

### 7.1.3 Peer 握手错误码 (-3210x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32100 | Peer certificate validation failed | 终止握手，检查证书链 |
| -32101 | Peer nonce expired | 重新发起 peer.hello |
| -32102 | Peer nonce reuse detected | 关闭连接，记录告警 |
| -32103 | Peer signature invalid | 终止握手，拒绝信任 |
| -32104 | Peer aid mismatch | 拒绝对端，检查证书配置 |
| -32105 | Peer handshake state invalid | 重试握手 |

### 7.1.4 Relay 错误码 (-3215x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32150 | Relay registration required | 先 relay.register |
| -32151 | Relay target not found | 稍后重试或回退模式 |
| -32152 | Relay sender mismatch | 检查注册 AID |
| -32153 | Relay payload too large | 缩小负载 |
| -32154 | Relay rate limited | 退避重试 |

### 7.1.5 搜索错误码 (-3216x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32160 | Search unavailable | 切换 AP |
| -32161 | Agent not found | 检查 AID |
| -32162 | Invalid search query | 修正查询 |
| -32163 | Snapshot stale | 等待同步 |
| -32164 | Change cursor expired | 用 snapshot 重建 |

### 7.1.6 任务错误码 (-3217x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32170 | Task not found | 检查 task_id |
| -32171 | Task state invalid | 先读取状态 |
| -32172 | Task input required | 调 task.send_input |
| -32173 | Task canceled | 停止推进 |
| -32174 | Task output too large | 用 storage.* |
| -32175 | Task access denied | 无权限 |
| -32176 | Task already accepted | 不重复 accept |
| -32177 | Task rejected | 停止或重建 |
| -32178 | Task delegation denied | 无委派权限 |
| -32179 | Task child limit exceeded | 减少子任务 |
| -32185 | Task completion blocked | 等子任务完成 |
| -32186 | Task failure recorded | 已终态 |

### 7.1.7 连接升级错误码 (-3218x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32180 | Peer upgrade unsupported | 保持当前模式 |
| -32181 | Peer upgrade expired | 重新发起 |
| -32182 | Peer upgrade rejected | 保持当前模式 |
| -32183 | Peer upgrade invalid endpoint | 丢弃提议 |
| -32184 | Peer switch denied | 等新通道认证 |

### 7.1.8 E2EE 错误码 (-3204x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -32040 | Group secret missing（缺少群密钥） | 发送 key_request 请求补发 |
| -32041 | Group epoch mismatch（epoch 不匹配） | 请求对应 epoch 的密钥 |
| -32042 | Group commitment invalid（成员承诺验证失败） | 告警，检查成员列表 |
| -32043 | Group not member（请求者非群成员） | 不重试 |
| -32044 | Group decrypt failed（群消息解密失败） | 检查密钥，可能需 key_request |

### 7.1.9 Group 错误码 (-3300x)

| 错误码 | 说明 | 客户端处理 |
|--------|------|-----------|
| -33001 | Group not found | 检查 group_id |
| -33002 | Group state invalid（群状态不允许该操作） | 检查群状态 |
| -33003 | Group suspended | 等待恢复或联系管理员 |
| -33004 | Group member limit reached | 不重试 |
| -33005 | Group already member | 不重试 |
| -33006 | Group not member | 先加入群 |
| -33007 | Group role insufficient | 检查权限 |
| -33008 | Group invite code invalid | 获取新邀请码 |
| -33009 | Group join rejected | 不重试 |

## 7.2 可重试 / 不可重试分类

| 分类 | 错误码 | 说明 |
|------|--------|------|
| **可重试** | -32010, -32101, -32151, -32154, -32163, -32040, -32041 | 临时状态，稍后可能恢复 |
| **不可重试** | -32001, -32003, -32004, -32100, -32102, -32103, -32104, -32175, -32043, -33001 | 永久性拒绝 |
| **需操作后重试** | -32002, -32005, -32013, -32150, -32164, -32172, -32044 | 需要先完成特定操作 |

## 7.3 连接状态机

### 7.3.1 Gateway 模式状态机

```
CONNECTED
  → auth.aid_login1
  → auth.aid_login2 (获取 token)
  → auth.connect(nonce, auth, protocol)
  → AUTHENTICATED
  → READY (可调用所有业务方法)
```

规则：
- auth.* 可在 auth.connect 之前调用
- auth.connect 成功即完成认证
- token 失效需重连

### 7.3.2 Peer 模式状态机

```
CONNECTED
  → initialize(mode=peer)
  → INITIALIZED
  → peer.hello
  → PEER_CHALLENGED
  → peer.hello_reply
  → PEER_VERIFIED
  → peer.confirm
  → AUTHENTICATED
  → notification/initialized
  → READY
```

规则：
- initialize 只建立模式上下文
- 任一 peer.* 失败应关闭连接
- AUTHENTICATED 后可调业务方法

### 7.3.3 Relay 模式状态机

```
CONNECTED
  → initialize(mode=relay)
  → INITIALIZED
  → relay.register
  → RELAY_REGISTERED
  → relay.forward(peer.hello)
  → ...peer.* 穿透认证...
  → AUTHENTICATED
  → notification/initialized
  → READY
```

规则：
- relay.register 仅建立 AID→连接映射
- 身份认证以 peer.confirmed 为准
- 未完成 peer.* 的连接不可投递业务消息

### 7.3.4 通用连接状态表

| 状态 | 允许的方法 | 说明 |
|------|-----------|------|
| CONNECTED | auth.connect, auth.*（仅 gateway 预认证） | 刚建立 WebSocket |
| INITIALIZED | peer.*, relay.* | 仅 peer/relay 模式 |
| AUTHENTICATED | 所有已协商方法 | 认证完成 |
| READY | 所有已协商方法 | notification/initialized 后 |

## 7.4 任务状态机

```
submitted → working → completed
         → rejected   → input_required → working
                       → failed
                       → canceled
```

| 状态 | 终态 | 可转到 |
|------|:----:|--------|
| submitted | | working, rejected |
| working | | input_required, completed, failed, canceled |
| input_required | | working, failed, canceled |
| rejected | 是 | |
| completed | 是 | |
| failed | 是 | |
| canceled | 是 | |

## 7.5 处理原则

- **-3210x**：Peer 握手错误，中止当前认证（参见 [04-Peer-子协议](04-Peer-子协议.md)）
- **-3215x**：Relay 错误，修正状态或回退模式（参见 [05-Relay-子协议](05-Relay-子协议.md)）
- **-3216x**：搜索错误，修正查询或切换 AP（参见 [08-服务协议](08-服务协议.md)）
- **-3217x**：任务错误，根据错误类型决定重试/放弃（参见 [08-服务协议](08-服务协议.md)）
- **-3218x**：升级错误，保留当前稳定通道（参见 [04-Peer-子协议](04-Peer-子协议.md)）
- **-3204x**：E2EE 错误，群密钥缺失时请求补发，解密失败时检查密钥版本（参见 [08-AUN-E2EE-Group](08-AUN-E2EE-Group.md)）
- **-3300x**：群组错误，根据错误类型决定重试/提示用户（参见 [10-Group-子协议](10-Group-子协议.md)）
