# 常见错误提示

AI 请求失败或网络波动时，聊天页会先显示「正在重试 N/6」的气泡，气泡首行标注本次重试的原因；重试耗尽仍失败时，错误会以红色气泡展示。本文说明这些提示的分类含义与排查思路。

## 重试提示分类

请求中途断线或服务端暂时异常时，Muse 会自动重试（最多 6 次、指数退避）。每次重试前气泡会先显示失败原因：

| 气泡提示 | 触发条件 | 可能原因与排查 |
| --- | --- | --- |
| 速率限制 (429) | 服务端返回 429 | 请求过于频繁，或套餐额度将尽。稍候自动重试即可；频繁出现请到供应商后台查看用量 |
| 服务器负载过高 (503) | 服务端返回 503 | 模型服务或中转站负载过高，属临时故障，等待自动重试即可 |
| 服务端错误 (5xx) | 服务端返回 500 / 502 / 504 等 | 服务端异常或网关问题，与你的配置无关，稍后重试 |
| 连接超时 | 建立连接或等待响应超时 | 网络较慢、服务无响应，或中转站响应慢。检查网络，必要时更换网络或节点 |
| 连接被拒绝 | 目标端口没有服务在监听 | 供应商 Base URL 填错（域名 / IP 或端口不对），或服务未启动，到「设置 → AI 供应商」核对 |
| DNS 解析失败 | 域名解析失败 | 网络未连通，或自定义 Base URL 的域名拼写错误 |
| 连接中断 | 连接建立后被断开、流被中断 | 网络抖动、代理不稳定或服务端主动断开。自动重试即可；反复出现请检查网络与代理设置 |
| SSL 握手失败 | TLS 证书校验失败 | 自定义 Base URL 时确认协议（https）与证书正确，或服务端证书异常 |
| 网络连接断开 | 其它网络层故障 | 移动网络切换、弱网环境，检查网络后手动重试 |
| 网络异常 | 无法归类的错误 | 查看具体错误文本，仍无法解决时可附日志反馈 |

## 常见 HTTP 错误码

请求失败时，重试气泡和最终错误气泡会附上 HTTP 状态码。常见状态码含义如下：

| 状态码 | 含义 | 可能原因 |
| --- | --- | --- |
| 401 | 鉴权失败 | API Key 错误、已过期或被吊销，到「设置 → AI 供应商」检查密钥 |
| 403 | 权限不足 | 密钥没有该模型或接口的权限、地域限制、余额为 0 |
| 404 | 接口不存在 | 自定义 Base URL 路径填错（如漏了 `/v1`），到供应商设置核对 |
| 429 | 速率限制 | 请求过于频繁或额度用尽，稍候重试或升级套餐 |
| 500 | 服务端内部错误 | 服务端临时故障，与配置无关 |
| 502 | 网关错误 | 中转站上游不可用 |
| 503 | 服务过载 | 服务端负载过高，稍候重试 |
| 504 | 网关超时 | 上游响应超时 |

## 工具返回的错误码

AI 调用工具失败时，聊天里的工具卡片会显示失败原因，其中一部分带固定错误码。与文件编辑相关的几个如下：

| 错误码 | 含义 | 怎么处理 |
| --- | --- | --- |
| `STALE_FILE` | 要改的文件已被**其他会话或用户**改过，AI 手上的内容已过期，本次修改**没有写入** | 不用管，AI 会重新读取该文件后重做。若反复出现，说明确实有另一个会话在同时改这个文件，建议先停掉其中一个 |
| `FILE_NOT_FOUND` | 目标文件不存在 | 确认路径；AI 通常会改用 `writeFile` 新建 |
| `NO_MATCH` | `editFile` 要替换的原文在文件里找不到 | 文件内容与 AI 的预期不一致，AI 会重读后重试 |
| `MULTIPLE_MATCHES` | 要替换的原文在文件中出现多次，无法确定改哪一处 | AI 会补充更多上下文后重试 |
| `FILE_EXISTS` | 写入时目标已存在且不允许覆盖 | 正常保护行为，AI 会改用 `editFile` 局部修改 |

## 多会话同时改同一个文件

Muse 支持多个会话（含子代理）并行工作。两个会话同时修改同一个文件时，如果放任不管，后写入的一方会**静默覆盖**前一方的改动，且双方都以为成功了。

为避免这种情况，Muse 做了三层保护：

- **同时刻**：同一文件的写入会被串行化，不会出现两个会话交错写同一个文件。
- **跨时刻**：AI 写完文件会记住版本；下次再改同一文件前会先比对，若期间文件已被改过就拒绝写入并提示重新读取（即上面的 `STALE_FILE`）。
- **原子写**：写文件时先写临时文件再整体替换，因此并发读取不会读到"写了一半"的内容，写入中途失败也不会留下半个文件。

你通常不需要干预。需要留意的是：**你自己在编辑器里改完文件后，AI 的写入也可能被判为过期**——这是预期行为，它会重新读取后再改，不会覆盖你的修改。反过来，若 AI 刚改过某文件而你在编辑器里保存，编辑器会提示冲突，让你选择覆盖还是放弃自己的修改。

### 撤销代码时的表现

「撤销到某个检查点」会尽量还原当时的文件内容，但**不会覆盖它不认识的改动**：

- 文件在检查点之后被**其他会话**改过 → 该文件被跳过，并在提示里列出，改动保留。
- 文件是**当前会话**自己改的 → 照常还原（这正是撤销的用途）。

已知局限：如果某个文件是这次对话中**新建**的，撤销时一律删除它，即使期间别的会话往里写过内容。删除前无法可靠判断，因此撤销这类文件时请留意提示。

::: tip 想减少冲突
让并行的会话尽量负责不同的文件。若两个会话确实要长期改同一批文件，建议错开执行，而不是同时跑。
:::

## 与多 Key 切换的关系

「设置 → AI 供应商」开启多 Key 后，只有**密钥本身有问题**的错误（鉴权失败、权限不足、限流、余额用尽）才会消耗失败计数并触发 Key 切换；服务器 5xx、请求超时、网络不可达等错误换 Key 也无法解决，因此不会误切换。未开启多 Key 时，限流（429）没有可切换的密钥，会像其它瞬时故障一样退避重试。详见 [AI 供应商与模型 → 多 Key](https://aicode.murk.top/md/guide/providers.md)。