# 错误码

> MCP 与 CLI 返回的稳定错误分类。

规范地址: https://keta1930.github.io/icml2026-mcp/zh/docs/reference/errors



失败文本格式为：

```text
error[code]: 可公开的短消息
```

Key、云端响应、搜索内容、向量、内部路径和未知异常细节不会返回给调用方。

## 稳定错误 [#稳定错误]

| Code                         | 默认是否可重试 | 含义                              |
| ---------------------------- | ------: | ------------------------------- |
| `invalid_request`            |       否 | 参数、长度、范围或必填项无效                  |
| `session_not_found`          |       否 | Session 不存在、过期或已关闭              |
| `session_capacity_reached`   |      稍后 | 活跃会话达到上限                        |
| `rate_limited`               |       是 | 来源或全局速率/次数达到上限                  |
| `server_busy`                |       是 | 服务队列已满或等待超时                     |
| `embedding_unavailable`      |      有时 | DashScope 暂时不可用、配置错误或返回了无法处理的响应 |
| `embedding_quota_exhausted`  |       否 | DashScope 免费额度或账户余额耗尽           |
| `index_unavailable`          |       否 | 本地索引缺失、损坏或契约不一致                 |
| `index_build_limit_exceeded` |       否 | 达到明确设置的索引构建输入上限                 |
| `internal_error`             |       否 | 未知服务错误，细节只留在安全日志边界              |

遇到 `rate_limited`、`server_busy` 或短暂的 `embedding_unavailable` 时退避后重试。额度、索引、配置和参数错误需要先解决对应问题。