主题

错误码与状态机 ​

错误码分层 ​

JSON-RPC 2.0 通用错误码 ​

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

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

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

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

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

Peer 握手错误码 (-3210x) ​

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

Relay 错误码 (-3215x) ​

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

搜索错误码 (-3216x) ​

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

任务错误码 (-3217x) ​

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

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

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

E2EE 错误码 (-3204x) ​

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

Group 错误码 (-3300x) ​

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

Stream 错误码 (-3340x) ​

错误码说明客户端处理
-33401Stream not found（流不存在）检查 stream_id
-33402Stream limit exceeded（达到流上限）等待其他流关闭后重试
-33403Stream permission denied（权限不足）不重试
-33404Stream already closed（流已关闭）不重试
-33405Stream invalid params（参数无效）检查参数
-33406Stream rate limited（速率限制）稍后重试
-33407Stream internal error（内部错误）稍后重试
HTTP 403push/pull token 无效，或 target_aid 不匹配检查 URL / aid
HTTP 404数据平面找不到流检查 stream_id
HTTP 410流已关闭不重试
HTTP 429拉流端数已达上限稍后重试

可重试 / 不可重试分类 ​

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

连接状态机 ​

Gateway 模式状态机 ​

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

规则：

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

Peer 模式状态机 ​

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

规则：

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

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.* 的连接不可投递业务消息

通用连接状态表 ​

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

任务状态机 ​

submitted → working → completed
         → rejected   → input_required → working
                       → failed
                       → canceled
状态终态可转到
submittedworking, rejected
workinginput_required, completed, failed, canceled
input_requiredworking, failed, canceled
rejected是
completed是
failed是
canceled是

处理原则 ​

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

AUN Protocol Documentation

Copyright © 2026