71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 错误码与常见问题（HTTP 层）
|
||
|
||
本 API 的错误分两类：
|
||
|
||
1) **HTTP 层错误**：接口直接返回 `success=false`，并用 HTTP 状态码表达错误类型。
|
||
2) **任务内错误**：接口本身 200，但轮询的 `events` 中出现 `type=error`，且任务状态变为 `failed`。
|
||
|
||
## 1. HTTP 状态码约定
|
||
|
||
| 状态码 | 何时出现 | 返回体示例 |
|
||
|---:|---|---|
|
||
| 200 | 成功（大多数 GET/POST） | `{ "success": true, ... }` |
|
||
| 202 | 成功但已进入后台执行（发送消息） | `{ "success": true, "task_id": "...", "status": "running", ... }` |
|
||
| 400 | 参数错误（缺字段/格式不对/路径非法） | `{ "success": false, "error": "..." }` |
|
||
| 401 | 未授权（缺 token 或 token 无效） | `{ "success": false, "error": "..." }` |
|
||
| 404 | 资源不存在（task/file/path 不存在） | `{ "success": false, "error": "..." }` |
|
||
| 409 | 并发冲突（已有 running/pending 任务） | `{ "success": false, "error": "已有运行中的任务，请稍后再试。" }` |
|
||
| 500 | 服务端内部错误（少见） | `{ "success": false, "error": "..." }` |
|
||
| 503 | 系统未初始化/资源繁忙（容器不可用等） | `{ "success": false, "error": "..." }` |
|
||
|
||
## 2. 常见错误与排查
|
||
|
||
### 2.1 401 Unauthorized
|
||
|
||
原因：
|
||
|
||
- 忘记带 `Authorization: Bearer ...`
|
||
- token 不存在或已被替换
|
||
|
||
排查：
|
||
|
||
- 检查 `data/api_users.json` 是否包含该 token 的 SHA256
|
||
- 修改 JSON 后是否重启服务（当前为启动时加载）
|
||
|
||
### 2.2 409 已有运行中的任务
|
||
|
||
原因：
|
||
|
||
- 同一个 API 用户在任务未结束时再次调用 `/api/v1/messages`
|
||
|
||
处理建议：
|
||
|
||
- 客户端 UI：禁用“发送”按钮，直到轮询显示 `status != running`
|
||
- 或先调用 `/api/v1/tasks/<task_id>/cancel` 再发送新任务
|
||
|
||
### 2.3 轮询一直 running，但没有 events
|
||
|
||
可能原因：
|
||
|
||
- 模型调用还没开始（排队/网络慢）
|
||
- 事件被缓冲上限丢弃（极少见，通常是轮询太慢）
|
||
|
||
建议：
|
||
|
||
- 将轮询间隔调小（0.5s~1s）
|
||
- 确保客户端从 `next_offset` 增量拉取，不要重复拉取导致 UI“看似卡住”
|
||
|
||
### 2.4 任务失败（轮询 events 里出现 type=error）
|
||
|
||
原因可能来自：
|
||
|
||
- 模型调用异常（上游 API/Key/网络）
|
||
- 工具执行异常（例如 web_search/extract_webpage 失败）
|
||
- 运行时资源问题
|
||
|
||
建议：
|
||
|
||
- 读取 `GET /api/v1/tasks/<task_id>` 返回的 `data.error`
|
||
- 同时遍历 `events` 中的 `type=error` 与 `system_message`，这些往往包含更具体原因
|
||
|