error-codes.md

错误码参考

错误码

统一 HTTP 错误体：

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "请求不符合当前契约"
  }
}

HTTP	code	当前场景
400	INVALID_ARGUMENT	严格 DTO、非法 JSON、缺参或类型错误
401	AUTH_REQUIRED	未登录或登录态失效
403	TOOL_FORBIDDEN	Tool 二次授权拒绝
403	ADMIN_FORBIDDEN	Admin 能力拒绝或未知管理路由
404	TOOL_FAILED	Tool 不存在
404	CONVERSATION_NOT_FOUND	当前 owner 范围找不到会话
409	CONVERSATION_CONFLICT	会话 revision 冲突
409	MCP_CONFIG_CONFLICT	MCP 名称或 revision 冲突
409	MCP_CONFIG_READ_ONLY	properties 模式写操作
500	TOOL_FAILED	Tool 执行异常
502	MCP_FAILED	MCP 协议或连接异常
502	MODEL_FAILED	未进入 SSE 流的模型网关异常
200 SSE	MODEL_FAILED	流内 error 帧

当前边界必须如实理解：

• MCP Admin 查找不存在的本地 Server，部分路径当前也落入通用 502 MCP_FAILED，没有独立 404 契约；test 端点则返回 200 和 ok=false。
• 405、415、406 发生在 Handler 选中之前，由路径限定的协议异常解析器处理：base-path 独占空间内返回上述统一信封（405 保留 Allow，415 保留 Accept），空间外完全交回宿主异常链，不影响宿主 Controller。
• 已通过宿主身份认证但 userId 为空或纯空白时，按 401 AUTH_REQUIRED 处理；框架不裁剪或重建 userId。
• Browser 本地还会产生 NETWORK_ERROR、ABORTED、INVALID_STATE 和 MODEL_PROTOCOL_ERROR。
• Browser Runtime 还会产生 AGENT_MAX_MODEL_CALLS、AGENT_MAX_TOOL_CALLS、AGENT_EXECUTION_TIMEOUT、MODEL_OUTPUT_LIMIT_EXCEEDED 和 TOOL_RESULT_LIMIT_EXCEEDED，五者都是不自动重试的明确终止。

---

Browser Runtime 错误码

实现时复用现有 AgentError 形状，不创造第二套错误体系：

错误码	触发条件
MODEL_PROTOCOL_ERROR	事件顺序、停止原因、Tool Call ID 或 Tool 批次形状违约
AGENT_MAX_MODEL_CALLS	达到已有模型调用上限
AGENT_MAX_TOOL_CALLS	本批预检发现将超过整轮 Tool 调用上限
AGENT_EXECUTION_TIMEOUT	整体 Execution 超过 maxDurationMs
MODEL_OUTPUT_LIMIT_EXCEEDED	单次模型调用聚合字符超限
TOOL_RESULT_LIMIT_EXCEEDED	Tool 结果文本超限

上述错误均为 retryable: false。是否重新发起一次新 Execution 由用户或宿主决定，框架不自动重试。