agent-Specialization/api_doc/errors.md

错误码与常见问题（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，这些往往包含更具体原因