错误处理
状态码、confirm、鉴权
错误处理
所有错误形如 {error:{code,message,retryable}, bridgeApiVersion}。
连接失败时先定位
- 先请求不带 token 的
curl -s "$BASE/status"。200 表示 Bridge 正常，问题在请求侧。 curl: (7) Failed to connect只说明本次连接失败，不代表服务未运行。再查 MarginNote 运行状态、Lab 开关、端口。- 沙盒、容器、网络策略可能挡住 loopback，表象与服务未运行相同。换不受限环境请求一次
/status。那边通这边不通，问题在当前环境。 lsof扫不到不代表未运行，受限环境的进程表可能残缺。连接状态看/status。- 403 与 401 见下表，与连接无关。
- MarginNote 重启有几秒空窗，遇到后等待重试。
状态码速查
| 码 | code | 含义与动作 |
|---|---|---|
| 401 | UNAUTHORIZED | 令牌缺失或无效。更换 token 后重试 |
| 403 | FORBIDDEN_ORIGIN | 请求带了 Origin 头。去掉 Origin 头重试 |
| 422 | CONFIRM_REQUIRED | 缺少 confirm，请求未执行。move、copy、delete、fold、metadata、hashtags 为真 dry-run，返回 422 与已校验的 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。在 MarginNote 中处理后重试 |
| 429 | PREPARE_BUSY | 已有 prepare 占用管线，含刚 discard 尚在取消检查点的。查看 runningJob 与 retryAfterSeconds，不重发 |
| 429 | SCAN_BUSY | 扫描并发已满，上限 2，底层串行。等待 retryAfterSeconds 后重发同一请求 |
| 500 | DISCARD_FAILED | 作业已取消但目录未删除，离线或只读外部目录时出现。稍后重试，或手动删除 bundleId 目录 |
| 504 | SCAN_TIMEOUT | 服务端超时。用更小页范围重试 |
| 400 | INVALID_JSON | body 不是合法 JSON，常见于标题引号或反斜杠未转义。修正转义后重试，与 confirm 无关 |
每个端点的 confirm 要求见各交互式页面的请求示例。