指南
错误处理与纪律
状态码速查、confirm 门清单、鉴权与订阅
错误处理与纪律
所有错误形如 {error:{code,message,retryable}, bridgeApiVersion}。
连不上先分清是谁的问题
- 先打不带 token 的
curl -s "$BASE/status"：200 = Bridge 活着，是你这边的问题，别让用户动 MN。 curl: (7) Failed to connect只说明「我连不上」≠「服务没跑」。再查 MN 是否运行、Lab 开关、端口（重发现）。- 调用方受限常见且表象相同（沙盒/容器/网络策略挡 loopback）：换不受限执行方式打一次
/status；那边通这边不通 = 你的环境问题。 - 别拿 lsof 扫不到当没跑：受限环境进程表残缺，以
/status为准。 403/401不是连接问题（见下表）。- MN 重启有几秒空窗，撞上等一下重试。
状态码速查
| 码 | code | 含义与动作 |
|---|---|---|
| 401 | UNAUTHORIZED | 令牌缺失/无效。重装换 token |
| 403 | FORBIDDEN_ORIGIN | 带了 Origin 头。去掉重试 |
| 403 | MAX_REQUIRED | 该写路由需 Max 而用户无订阅。该写不重试不绕路，只读继续 |
| 422 | CONFIRM_REQUIRED | 缺 confirm:true 且未执行。其中六个重动词为真 dry-run（已跑完全部只读校验，details 可直接复述给用户）；其余端点仅门控，未做对象校验，用只读端点自核 |
| 422 | HASHTAG_ROUTE_REQUIRED | 用 text 接口写标签。走 POST /notes/hashtags，details 有规范示例 |
| 422 | 其它 | 参数错：页码越界/层级/标签路径/preset 白名单外等，按 details 修 |
| 404 | TOPIC_NOT_FOUND 等 | 集被删/在回收站，回①重选 |
| 409 | SUBMIT_IN_FLIGHT | 同一 bundle 上一 submit 还在跑。等 retryAfterSeconds 后查 GET /bundles，多半已导完，勿重发 |
| 409 | TITLE_MISMATCH | 删集时 expectedTitle 对不上，details.actualTitle 为真值 |
| 409 | COMMENT_CHANGED | 评论被改过，重读 batch-get 再来 |
| 409 | USER_EDITS_PRESENT | submit/恢复时用户手改过，展示 changedNodes 获同意后带 force:true |
| 409 | STUDY_SET_IN_USE | 回退时目标集正开着（闪退风险）。切走再试 |
| 409 | TOC_GENERATION_IN_PROGRESS | 用户正 App 内生成 AI 目录，写入会被覆盖。约 1 分钟后先 GET outline |
| 409 | PREPARE_CANCELLED | 同步 prepare 被并发 discard 取消。包已无，勿用其路径 |
| 409 | DOCUMENT_IN_USE | 删文档时仍有卡片锚定（details 有卡数）。转用户去 MN 决定 |
| 409 | IMAGE_SOURCE_CHANGED / OCCLUSION_CHANGED | 挖空指纹变了。重读重预览，不覆盖 |
| 429 | PREPARE_BUSY | 已有 prepare 占管线（含刚 discard 尚在取消检查点）。别再发，看 runningJob/retryAfterSeconds |
| 429 | SCAN_BUSY | 扫描名额满（上限 2，底层串行）。等 retryAfterSeconds 重发同一请求 |
| 429 | EXPORT_BUSY | 已有文档/脑图导出在跑。等待 |
| 500 | DISCARD_FAILED | 作业已取消但目录没删掉（离线/只读外部目录）。稍后重试或手工删 bundleId 目录 |
| 504 | SCAN_TIMEOUT | 看门狗超时。用更小页范围重试 |
| 400 | INVALID_JSON | body 非法 JSON（标题引号/反斜杠未转义常见）。修转义，与 confirm 无关 |
每个端点的 requiresMax / confirm 要求见接口总览，交互式页面右上角也有标记（x-requires-max / x-requires-confirm 见 OpenAPI）。