常见错误与处理

本指南汇总了日常使用中最常见的错误及其解决方案，按症状分类方便快速查找。

什么时候用

调用API时返回错误码
控制台操作出现异常提示
模型调用失败或超时
用户无法登录或权限异常

按症状排查

401 / 认证失败

症状：

调用API返回认证错误
控制台提示「登录已过期，请重新登录」
提示「API Key无效」

排查与处理：

登录会话已过期，重新登录
API Key可能已失效或用错了地方。在「用户管理」-> 对应用户的API Key弹窗检查Key是否存在，必要时重新创建
确认API Key状态为「启用」

相关文档：11-管理用户API Key

403 / 无权限

症状：

提示「无权限访问该模型」或「模型不在白名单中」
提示「客户端不在白名单中」
调用被拒绝

排查与处理：

左侧菜单 -> 「系统设置」 -> 配置「允许的API客户端」
左侧菜单 -> 「用户管理」 -> 对应用户 -> 「更多」 -> 「模型」 -> 添加模型到白名单
左侧菜单 -> 「模型管理」 -> 确认模型状态为「启用」

重要提醒：白名单为空 = 全部拒绝，不是「允许全部」。

相关文档：12-配置用户模型白名单

422 / 参数验证失败

症状：

创建或编辑资源时返回错误
提示「参数验证失败」或具体字段的错误信息
创建模型时提示「显示名称不能以group-开头」

排查与处理：

仔细阅读错误提示，定位具体问题
修改显示名称，避免以group-开头
使用不同的名称创建资源
修正JSON格式，或删除JSON配置尝试保存

429 / 请求过于频繁

症状：

接口返回「请求过于频繁，请稍后再试」
提示配额不足或限流

排查与处理：

降低请求频率，增加等待时间
左侧菜单 -> 「日志和统计」 -> 「会话记录管理」 确认调用量
左侧菜单 -> 「模型管理」 -> 「模型组」 -> 配置包含多个模型的组实现自动降级
联系平台管理员调整限流阈值

503 / 服务不可用

症状：

调用时提示「服务不可用」或「模型未配置」
使用智能体时更易出现

排查与处理：

智能体没绑定模型且没设默认模型。在「智能体管理」-> 编辑智能体绑定模型，或在「系统设置」设默认模型
左侧菜单 -> 「模型管理」 -> 启用模型
检查模型供应商连接是否正常

相关文档：05-设置默认模型

模型鉴权失败

症状：

调用时提示「上游模型鉴权失败」
「自动获取模型」功能返回错误

排查与处理：

左侧菜单 -> 「模型管理」 -> 对应供应商行 -> 点击 「编辑」 -> 更新API Key
确认供应商类型选择正确
确认API Base URL是否正确（如有）

相关文档：02-接入模型供应商

API Key用错地方 / 接口不存在

症状：

调用API返回「接口不存在」
使用API Key调用管理功能返回认证失败

排查与处理：

确认API Key用于对话/Embedding调用，不是管理操作
管理操作在控制台完成，不需要API Key
检查调用地址是否正确

显示名称以 group- 开头 / 命名冲突

症状：

创建模型时提示「显示名称格式不合法」
提示「名称已存在」但列表中看不到同名模型

排查与处理：

修改显示名称，避免以group-开头
删除或重命名已存在的同名资源
检查是否有禁用状态的同名模型或同名模型组

白名单空 = 全拒绝 / 用户看不到任何模型

症状：

提示「无可用模型」
用户所有模型调用都被拒绝

排查与处理：

左侧菜单 -> 「用户管理」 -> 对应用户 -> 「更多」 -> 「模型」 -> 添加模型到白名单
或配置「模型组白名单」
确认至少有一个模型状态为「启用」

相关文档：12-配置用户模型白名单

关键词冲突 / 智能体触发混乱

症状：

用户消息触发了错误的智能体
关键词匹配结果不符合预期

排查与处理：

左侧菜单 -> 「智能体管理」 -> 编辑智能体 -> 修改或删除重复的关键词
确认没有重复的关键词
测试正则表达式是否过于宽泛

相关文档：06-创建并配置智能体

流式响应中断 / 没收到完整回复

症状：

流式调用中途断开
只收到了部分回复内容

排查与处理：

左侧菜单 -> 「日志和统计」 -> 「会话记录管理」 -> 查看具体对话的错误详情
检查网络连接是否稳定

MCP工具列表为空

症状：

在「MCP 网关」中看不到可用工具
提示「未找到任何工具」

排查与处理：

左侧菜单 -> 「MCP 网关」 -> 「MCP Server 管理」 -> 启用Server、修复连接、刷新工具
检查Server状态是否为「已启用」且「在线」
点击「刷新工具」按钮

相关文档：15-注册上游MCP Server、16-同步工具与查看权限

MCP工具调用失败

症状：

智能体调用MCP工具时提示执行失败
提示「工具不存在」或「无权限」

排查与处理：

左侧菜单 -> 「MCP 网关」 -> 「调用日志」 -> 查看详细错误
左侧菜单 -> 「MCP 网关」 -> 「权限管理」 -> 调整工具权限

相关文档：17-排查调用日志

排查顺序总览

遇到问题时，建议按以下顺序排查：

先看错误提示：401/403/422/429/503 分别指向不同问题
认证问题：查「用户管理」->「API Key」
权限问题：查模型白名单和客户端白名单
Agent问题：查智能体绑定模型和默认模型
内容安全：查安全事件日志
MCP问题：查工具刷新和调用日志
上游问题：查模型供应商连接和平台调用记录

深入

补充排错内容

按症状排查（补充）

401 / 认证失败（补充）

Token 有效期说明：

access_token：有效期 2 小时，用于调用所有管理接口
refresh_token：有效期 7 天，过期后需要重新登录
每次登录会全局吊销该租户旧的 refresh_token

密码或角色变更不会立即吊销 access token（需等 2 小时自然过期）；仅同租户其他用户登录会通过 refresh_jti 覆盖吊销旧 refresh_token。

403 / 无权限（补充）

403 主要出现在普通用户对未授权模型/Agent 的调用路径，管理员操作一般不返 403（除非跨租户）。

可能原因：

客户端不在允许的 API 客户端白名单中
用户模型白名单为空，非 Agent 路径直接拒绝
用户白名单不包含请求的模型
带 agent_id 时，请求 model 与 Agent 绑定模型/模型组或租户默认模型/默认模型组不一致，Agent 路径不会按用户白名单放行

503 / 服务不可用（补充）

详见「模型管理」常见坑。

内容安全问题（补充）

查看安全事件日志，筛选 event_type=policy_violation，对照命中规则和请求内容。

流式响应问题（补充）

查看调用记录状态和错误类型。

MCP 工具问题（补充）

工具名格式不正确；未使用 {server_name}__{tool_name}；上游限流或超时；工具被策略拒绝。查看 MCP 调用日志；检查 status 和 deny_reason；对比 tools/list 返回的工具名；查看上游 MCP Server 日志。

内置聊天提示「请先设置默认 API Key」（补充）

当前用户没有默认 API Key。进入「用户管理→API Key」，查看当前用户是否有默认 Key。给当前用户创建一把 API Key，并设置为默认。

创建用户、Agent、技能时提示「已存在」（补充）

name 在当前租户内已存在。在对应列表页搜索该名称，确认是否已有禁用或历史资源占用。改名后创建，或删除旧资源后再创建。

平台管理员看不到其他租户的 Agent（补充）

普通 list 接口仍按当前租户过滤；include_market=true 只用于查看市场 Agent；MCP Server 状态 PATCH 才支持平台管理员跨租户。按接口语义查询市场资源或目标租户资源，不要假设普通 list 自动跨租户。

修改 S3 SecretKey 没生效或没法清空（补充）

敏感字段规则是留空保留原值，传新值才覆盖；不能通过普通更新清空 SecretKey。需要替换时传新值；需要保留时留空。普通更新不支持清空。

Token 失效后所有请求 401（补充）

见上文 401 / 认证失败。

系统任务无法删除（补充）

任务是系统任务，is_system_task=true。系统任务只能用系统任务配置接口启停或调整配置。

创建 ModelItem 提示 display_name 不合法（补充）

display_name 以 group- 开头；同租户重复；与模型组名冲突。修改 display_name，不要以 group- 开头，并避免与模型或模型组重复。

普通租户 admin 创建 Local 技能被拒（补充）

SaaS 模式下不允许租户 admin 编辑可执行代码；只有 Private 模式 admin 可创建 Local 技能或编辑相关代码。SaaS 模式下改用非 Local 技能，或由平台管理员代部署；私有化场景可切换到 Private 模式。

提交工单请求帮助：29-工单
查看审计日志了解操作历史：26-查审计与安全事件
日志和统计查看：路由决策日志/路由统计分析/客户端拦截日志/安全事件/操作审计/Token统计/Hindsight统计/通知日志