错误码
界面和 API 返回的错误大多带一个 code。按分类列出每个码的 HTTP 状态、含义和处理方法，以及几条不带 code 的常见提示。
网关的错误响应为 {"detail": "<中文说明>", "code": "<错误码>", "params": {...}}。界面按当前语言显示说明，API 调用方按 code 判断，params 中的值填入说明。
Zabbix 和模型返回的原始报错只写入服务端日志，不出现在响应中。需要细节时执行 docker compose -f docker-compose.prod.yml logs gateway 查看。
| 错误码 | HTTP | 含义 | 处理 |
|---|
login_required | 401 | 未登录或会话过期 | 重新登录 |
permission_denied | 403 | 当前角色（params.role）没有该权限（params.permission） | 联系管理员，在设置的 角色权限 中调整 |
admin_session_or_token_required | 403 | 管理操作没有有效会话，也没有 X-RST-Admin-Token | 重新登录，或运维脚本携带 RST_ADMIN_TOKEN |
setting_locked_by_env | 409 | 该设置（params.key）由环境变量 params.env 固定 | 在 .env 中修改后重建容器 |
eula_not_accepted | 403 | 当前账号还没有同意这一版许可协议（params.version） | 阅读后同意 |
rate_limited | 429 | 请求过于频繁 | 等待 params.seconds 秒。限速值由 RST_RATELIMIT_* 调整 |
| 错误码 | HTTP | 含义 | 处理 |
|---|
feature_needs_standard | 403 | params.feature 需要专业版或企业版。可能的值：alert_triage（告警收敛）、alert_investigation（故障调查、远程 ping 和 traceroute）、detection_rule_copilot（触发器与监控配置、维护窗口助手）、platform_ops_copilot（平台体检） | 激活许可，见版本对比 |
reports_need_professional | 403 | 运维报告、定时报告和巡检需要专业版或企业版 | 激活许可 |
feature_needs_enterprise | 403 | params.feature 需要企业版。可能的值：sso_oidc（单点登录、审计员角色）、offline_issuance（离线激活） | 激活企业版许可。专业版许可请用在线激活 |
feature_sealed | 403 | 没有有效许可，或许可不含该功能的功能密钥 | 激活包含该功能的许可。离线许可缺少功能密钥时联系我们重签 |
license_invalid | 403 | 许可校验失败（签名、解密或篡改），除登录、许可协议和产品激活页外全部拒绝 | 联系销售重新签发 |
license_status_abnormal | 403 | 许可状态异常 | 查看产品激活页 |
users_need_professional | 403 | 社区版只能有 1 个用户，新建或启用账号时返回，界面弹出升级提示 | 激活专业版或企业版许可 |
user_seats_exhausted | 403 | 许可的 params.seats 个用户席位已用完，新建或启用账号时返回 | 停用一个账号，或增购席位 |
seats_exceeded_admin_only | 403 | 启用的账号数超过当前许可的 params.seats 个席位（许可过期、被吊销或席位变少），非管理员登录或发起请求时返回 | 管理员续期许可，或在用户页停用多余账号 |
machine_id_unreadable | 503 | 读不到本机硬件标识（params.reason） | 检查 state/machine-id 是否存在并挂载为 /etc/machine-id |
license_deactivate_error | 500 | 撤销激活时出错（params.reason） | 按原因处理 |
| 错误码 | HTTP | 含义 | 处理 |
|---|
zabbix_unreachable | 502 | 连不上 Zabbix API | 检查 ZABBIX_URL、网络和证书 |
zabbix_auth_failed | 测试连接结果 | API token 或用户名、密码无效 | 更换凭据，见 Zabbix 账号权限 |
zabbix_request_failed | 测试连接结果 | Zabbix API 返回错误（params.reason 是 Zabbix 原文） | 按原因处理 |
zabbix_not_api | 400 | 地址不是 Zabbix JSON-RPC 接口 | 地址以 /api_jsonrpc.php 结尾 |
zabbix_url_invalid | 400 | 地址不是 http(s) URL，或带了用户名密码 | 改成 https://<主机>/api_jsonrpc.php |
zabbix_version_unsupported | 502 | Zabbix 版本（params.version）低于 6.0 | 升级 Zabbix。已验证 6.0、6.4、7.0、7.2、7.4 |
zabbix_query_failed | 502 | Zabbix 查询失败 | 查看网关日志中的 zabbix_call_failed |
zabbix_call_rejected、zabbix_call_rejected_repair_failed | 400 | Zabbix 拒绝了生成的 API 调用，自动修正没有成功 | 在对话中展开 API 调用，编辑后重试，或换一种问法 |
secret_reentry_required | 400 | 连接地址已改，旧凭据不会发往新地址 | 重新填写 token、密码或 API key |
index_not_whitelisted | 403 | 主机组 params.index 不在主机组白名单（params.patterns）内 | 由管理员在 设置 的 主机组白名单 中添加 |
hosts_not_whitelisted | 403 | 部分主机不在主机组白名单内 | 同上 |
group_required_by_whitelist | 400 | 已启用主机组白名单，请求没有指定主机组 | 选择一个主机组 |
host_group_not_found | 404 | Zabbix 中没有主机组 params.group | 核对名称 |
host_not_found、host_not_in_topology | 404 | 主机 params.hostid 不存在，或不在拓扑中 | 无 |
hostid_not_numeric、hostid_or_group_required、too_many_hosts | 400 | hostid 不是数字。缺少 hostid 或主机组。一次超过 params.limit 台主机 | 修改请求 |
maintenance_not_found | 404 | 维护 params.id 不存在或已删除 | 无 |
maintenance_not_managed | 403 | 维护 params.name 不是本产品创建的 | 在 Zabbix 中删除 |
maintenance_out_of_scope | 403 | 维护涉及主机组白名单之外的主机或主机组 | 在 Zabbix 中处理 |
diagnostics_script_scope_invalid | 403 | Zabbix 脚本 params.script 的适用范围不是「手动主机操作」 | 在 Zabbix 中修改脚本的适用范围 |
| 错误码 | HTTP | 含义 | 处理 |
|---|
llm_timeout | 504 | 模型调用超时 | 稍后重试，或在 AI 配置中调大超时 |
llm_unavailable | 503 | 所有启用的 provider 都失败 | 检查 provider 配置和到模型端点的网络 |
llm_unparseable | 502 | 模型返回的内容无法解析 | 重试 |
llm_request_failed | 502 | 其他模型调用失败 | 查看网关日志中的 llm_call_failed |
model_required | 400 | 没有填写模型名 | 填写 |
connection_test_failed | 400 | 测试连接失败（params.reason） | 按原因处理 |
kb_dim_mismatch | 409 | 知识库用 params.index_dims 维向量建立，当前模型是 params.real_dims 维 | 换回原来的 Embedding 模型，或删除知识库文档后重新上传 |
| 错误码 | HTTP | 含义 |
|---|
alerts_aggregate_failed | 502 | 告警统计失败（params.reason） |
platform_checkup_failed | 500 | 平台体检失败，详见网关日志 |
nothing_to_explain | 400 | 查询没有返回任何行，没有可解读的内容 |
invalid_time | 400 | params.what 不是合法时间（params.value） |
dsl_empty、cluster_empty、investigation_empty、markdown_empty | 400 | 请求中没有 Zabbix API 调用、告警簇、调查结果或正文 |
body_not_object | 400 | 请求体不是 JSON 对象 |
| 错误码 | HTTP | 含义 | 处理 |
|---|
push_failed | 500 | 推送失败（params.reason） | 查看投递记录 |
delivery_not_retryable | 409 | 该投递不存在，或正在排队、发送 | 无 |
notify_target_not_found | 404 | 推送目标不存在 | 无 |
webhook_url_required、webhook_must_be_https、webhook_host_invalid、feishu_url_must_be_https、feishu_host_not_allowed、feishu_path_invalid、dingtalk_path_invalid、wecom_key_missing、slack_path_invalid | 400 | 机器人地址为空或格式不对 | 从群机器人设置中原样复制 |
smtp_host_required、smtp_port_not_int、smtp_port_out_of_range、smtp_security_invalid、smtp_from_invalid | 400 | 发件服务器配置格式错误 | 修改配置 |
recipients_required、recipient_invalid | 400 | 收件人为空或格式错误 | 修改配置 |
unknown_channel、unknown_period、periods_not_array、hour_not_int、hour_out_of_range、severity_threshold_invalid、name_required | 400 | 渠道、排期或名称参数不合法 | 修改配置 |
egress_metadata_refused | 400 | params.value 是云元数据地址，任何渠道都不允许推送 | 换一个地址 |
egress_entry_invalid、egress_too_many | 400 | 额外地址不是合法的主机名、IP 或网段。每个渠道最多 params.limit 条 | 修改配置 |
| 错误码 | HTTP | 含义 | 处理 |
|---|
content_token_required | 400 | 请求中没有内容包令牌 | 粘贴签名内容包令牌 |
content_pack_rejected | 400 | 内容包验签失败、版本比当前旧或不兼容（params.reason） | 确认令牌来源和版本 |
content_pack_apply_failed | 500 | 内容包应用时服务端出错 | 查看网关日志 |
no_release_to_download | 400 | 当前没有可下载的新版本 | 先选择 立即检查 |
release_download_failed | 400 | 下载或暂存失败：验签失败、磁盘不足或更新脚本版本过旧（params.reason） | 按原因处理 |
release_download_server_error | 500 | 下载时服务端出错 | 查看网关日志 |
rollback_failed、rollback_server_error | 400、500 | 内容包回滚失败 | 按原因处理 |
以下提示只有中文说明，没有 code，英文界面也显示中文原文。
| 提示 | HTTP | 处理 |
|---|
| 请先登录。 | 401 | 重新登录 |
| 用户名或密码错误。 | 401 | 无 |
| 登录失败次数过多，请稍后再试。 | 429 | 5 分钟后重试 |
| 该账号仍在使用出厂默认密码，禁止远程登录。 | 403 | 设置 RST_ADMIN_PASSWORD_HASH，或在本机登录后改密码 |
| 跨站请求被拒绝（Origin 与本站不一致）。 | 403 | 从产品页面本身操作 |
| License 激活失败：… | 400 | 冒号后是原因，见常见问题 |
| License 激活异常：… | 500 | 查看网关日志 |
