错误码说明

怎么读一个错误码

AI 调用工具失败时，响应里 ok:false，error 字段有两种形态：

• E_ 开头的码：机器可判定的失败。码本身稳定，文案可能改。
• 一句人话：本地侧的失败（文件、磁盘、原生库），没有码。

{ "ok": false, "error": "E_SPACE_FORBIDDEN" }

判处理方式看这个码，不要看文案——文案是给人读的，码才是契约。

本地侧

码 / 现象	含义	怎么办
CHAIN BROKEN（xbb verify 的输出）	事件哈希链对不上：文件被截断，或某一行被外部工具改过	立刻停止写入并备份 memory.db。链断了不能靠继续写入修复，需要从备份恢复
E_NO_WINDOW	在没有图形界面的环境里想开托盘/窗口	改用 xbb serve --headless
启动即退出（Windows 11 24H2）	系统目录的旧版 onnxruntime 被优先加载，原生层中止	升级到 0.4.42+（xbb update），见常见问题
listen EADDRINUSE 17630	本地服务端口被占用（通常是自己已经开了一个）	托盘里看看是不是已在运行；确实要并存就换端口
工具列表为空	客户端没读到配置，或没重启	见常见问题 · 看不到工具

云端返回的码

本地版绑定组织之后，写入/检索会打到服务端，这些码才可能出现。没绑定就不会遇到。

校验与权限

码	含义	怎么办
E_VALIDATION	入参不合法（超长、格式错、必填缺失）	让 AI 修参数重试；反复出现说明是客户端拼错了字段
E_NOT_FOUND	按 id 找不到，或无权看到	注意：无权可见也返回这个码，是刻意的——不泄露”这条存在但你不能看”
E_SPACE_FORBIDDEN	想写入/放宽到别人子树里的空间	只能授权到自己子树内的空间，越界整笔被拒
E_NOT_MEMBER	不是该组织成员	让管理员邀请，或换正确的组织
E_MEMBER_DISABLED	成员被禁用	联系管理员解禁
E_ORG_FROZEN	组织被冻结（欠费或违规）	联系管理员

账号与会话

码	含义	怎么办
E_KEY_INVALID	绑定密钥无效或已被吊销	在控制台重新生成绑定票 / 密钥，再 xbb bind
E_SESSION_INVALID	登录会话过期	重新登录账号中心；客户端会引导
E_ACCOUNT_LOCKED	连续失败导致账号锁定	等锁定期结束或走找回流程
E_SMS_RATE_LIMITED	验证码发太频	等下一窗口
E_SMS_CODE_INVALID	验证码错或已过期	重新获取，注意有效期

配额与计费

码	含义	怎么办
E_QUOTA_EXCEEDED	超出可用额度/余额不足	到账号中心看额度与余额，充值或等下月重置
E_PAY_CHANNEL	支付渠道异常	换支付方式；反复失败联系客服
E_PURGE_TOO_LARGE	一次清理请求的数据量过大	分批清理

邀请

码	含义	怎么办
E_INVITE_INVALID	邀请码不存在	核对链接是否被截断
E_INVITE_EXPIRED	邀请过期	让管理员重发
E_INVITE_EXHAUSTED	邀请名额用尽	让管理员加名额
E_INVITE_PHONE_NOT_ALLOWED	该手机号不在允许名单内	联系管理员

其它

码	含义	怎么办
E_DUPLICATE_CONTENT	同内容已存在	通常无害。如果确实要写两条一模一样的，说明场景本身可能该用 supersede
E_OWNER_PROTECTED / E_SELF_PROTECTED	对拥有者/自己执行了不允许的操作（如移除自己、停用 owner）	换一个操作者；转移所有权走控制台流程
E_INTERNAL	服务端内部异常	重试一次；持续出现请反馈，带上时间点

排查前先做三件事

xbb version   # 版本号，反馈时必带
xbb verify    # 本地链是否完好
xbb cloud     # 当前是本地模式还是云端模式、绑的是哪个组织

这三条能覆盖大部分”看起来很奇怪”的情况——尤其是”记忆写到别处去了”，十次里有九次是模式或组织绑错了。