# 错误码与常见问题（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 用户在**同一个 workspace** 的任务未结束时再次调用 `/api/v1/workspaces/{workspace_id}/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`，这些往往包含更具体原因