错误码
网关返回的每个错误都带一个 code。按场景列出全部错误码的含义和处理方法。
网关的错误响应为 {"detail": "<中文说明>", "code": "<错误码>", "params": {...}}。界面按当前语言显示说明，API 调用方按 code 判断，params 中的值填入说明。
| 错误码 | 含义 | 处理 |
|---|
login_required | 未登录或会话过期 | 重新登录 |
sso_identity_required | 已启用 SSO，但请求没有已验证身份 | 从 SSO 入口登录，检查 oauth2-proxy |
read_only | 只读角色不能执行写操作 | 联系管理员 |
admin_role_required | 当前角色（params.role）没有管理权限 | 联系管理员 |
admin_group_required | SSO 账号不在 RST_RBAC_ADMIN_GROUPS 的组中 | 由 IdP 管理员加组 |
admin_session_or_token_required | 管理接口需要有效会话或 RST_ADMIN_TOKEN | 重新登录，或在 X-RST-Admin-Token 请求头中提供令牌 |
admin_login_required | 管理操作需要先登录 | 登录 |
metrics_token_required | 抓取 /metrics 需要令牌 | 在 X-RST-Metrics-Token 请求头（或 Authorization: Bearer）中提供 RST_METRICS_TOKEN |
csrf_rejected | 跨站请求被拒绝，来源校验失败 | 从产品页面本身操作 |
rate_limited | 触发限速 | 等待 params.seconds 秒；团队较大时调整 RST_RATELIMIT_* |
| 错误码 | 含义 | 处理 |
|---|
bad_credentials | 账号或密码错误 | 无 |
login_throttled | 登录失败次数过多 | 5 分钟后重试 |
default_password_refused | 仍在使用出厂密码，拒绝远程登录 | 设置 RST_ADMIN_PASSWORD_HASH 后重启；局域网试验可设 RST_ALLOW_DEFAULT_PASSWORD=1 |
password_login_disabled | 未启用密码登录 | 从 SSO 入口登录 |
password_change_not_supported | 只有密码登录的账号可以在界面修改密码 | 在身份系统中修改 |
password_in_env_only | 单账号部署的密码保存在 RST_ADMIN_PASSWORD_HASH 中 | 生成新哈希写入 .env 后重启 |
current_password_wrong | 当前密码不正确 | 无 |
password_too_short、password_min_length | 密码少于 8 位 | 无 |
user_db_not_configured | 未配置用户表，不能管理多个账号 | 设置 RST_USER_DB_URL |
username_required、user_exists、user_not_found | 账号名为空、已存在或不存在 | 无 |
unknown_role | 角色不在可选范围（params.choices）内 | 无 |
last_admin_locked、last_admin_undeletable | 最后一个启用的管理员不能停用、降级或删除 | 先创建另一个管理员 |
cannot_disable_self、cannot_delete_self | 不能停用或删除自己的账号 | 由其他管理员操作 |
| 错误码 | 含义 | 处理 |
|---|
feature_needs_standard | params.feature 需要专业版及以上许可 | 激活许可 |
incident_report_needs_standard | 事件报告需要专业版及以上许可 | 激活许可 |
platform_checkup_needs_standard | 平台体检需要专业版及以上许可 | 激活许可 |
feature_sealed | 本机没有激活的许可，或许可不含该功能，该功能未开放 | 在 产品激活 页激活包含该功能的许可 |
reports_need_professional | 运营报告需要专业版及以上许可 | 激活许可 |
users_need_professional | 社区版只能有 1 个用户 | 激活专业版或企业版许可 |
user_seats_exhausted | 启用的账号已达许可的用户数（params.seats） | 停用一个账号，或增购用户数 |
license_invalid | 验签、解密或篡改校验失败 | 联系销售重新签发 |
license_expired | 过期超过 7 天宽限期，服务锁定 | 续期 |
license_revoked | 许可已撤销 | 联系销售 |
license_heartbeat_lost | 连续 7 天没有心跳，服务锁定 | 检查到许可服务器的网络 |
license_status_abnormal | 许可状态异常 | 联系支持 |
machine_id_unreadable | 读不到本机硬件标识（params.reason） | 检查 /etc/machine-id 挂载 |
license_activate_failed | 激活被拒绝（params.reason：名额用完、指纹不符、不属于本产品等） | 按原因处理 |
license_activate_error、license_deactivate_error | 激活或撤销过程出错（params.reason） | 按原因处理 |
| 错误码 | 含义 | 处理 |
|---|
es_unreachable | 无法连接 Elasticsearch | 检查 ES_URL、网络和证书 |
es_auth_failed | Elasticsearch 认证失败 | 检查 ES_USER、ES_PASSWORD，或 ES_API_KEY |
es_forbidden | 账号无权访问该索引 | 为 Elasticsearch 角色添加权限 |
es_index_not_found | 索引不存在 | 检查索引或别名名称，以及是否已被滚动删除 |
es_timeout | Elasticsearch 查询超时 | 缩小时间范围或结果条数；调整 RST_ES_TIMEOUT_S（默认 30 秒） |
es_request_failed | 其他 Elasticsearch 错误（params.reason） | 按原因处理 |
es_audit_query_failed、es_resolve_index_failed | 查询审计日志或解析索引失败（params.reason） | 按原因处理 |
index_not_whitelisted | 索引不在 RST_INDEX_WHITELIST（params.patterns）内 | 在系统设置的 索引白名单 中添加模式 |
index_is_internal | 索引是产品自身的存储，不能作为查询目标 | 在对应页面查看 |
no_queryable_index | 没有可查询的索引 | 检查数据源连接，或放宽索引白名单 |
dsl_validation_failed | 查询未通过只读校验（params.reason） | 修改查询 |
nothing_to_explain | 结果既无聚合也无样本，没有可解读的内容 | 无 |
| 错误码 | 含义 | 处理 |
|---|
llm_generation_failed | 模型生成失败（params.reason） | 在 AI 配置中查看 provider 状态 |
llm_timeout | 模型调用超时 | 把 provider 超时调到 90 秒以上；把送模型的聚类数从默认 30 降到 10 |
llm_first_token_timeout | 超过 params.limit_s 秒仍未开始作答，已中止 | 换一种问法重试，或调低推理强度 |
providers_empty | provider 列表为空 | 至少配置一个 |
model_required | 未填写 model | 无 |
connection_test_failed | 测试连接失败（params.reason） | 按原因处理 |
embedding_not_configured | 未配置向量模型 | 在 AI 配置的知识库向量模型中配置 |
kb_dims_mismatch、kb_dim_mismatch | .rst_copilot_kb 的维度与当前向量模型不一致 | 换回原模型，或删除 .rst_copilot_kb 后重新上传文档 |
kb_upload_failed、kb_list_failed、kb_search_failed、kb_delete_failed | 知识库上传、列表、检索或删除失败 | 查看网关日志 |
| 错误码 | 含义 |
|---|
investigation_failed、triage_failed、detection_rule_failed、report_generation_failed、incident_report_failed、platform_checkup_failed、alerts_aggregate_failed | 对应功能失败，params.reason 含细节 |
field_dict_failed、explain_log_failed、explain_result_failed、suggest_angles_failed | 字段字典、日志解读、结果解读或追问角度生成失败 |
detection_rule_rejected | 检测规则被拒绝（params.reason） |
too_many_alerts | 一次分诊最多 params.cap 条告警 |
alerts_or_index_required | 分诊需要 alerts 或 index 之一 |
incident_input_required | 事件报告需要 alert、alert_id、investigation 之一 |
conversation_not_found、analysis_record_not_found | 会话或分析记录不存在或已过期 |
failed_case_not_found | 失败用例不存在 |
kibana_link_failed、kibana_data_view_not_found | 生成 Kibana 深链失败；Kibana 中没有匹配该索引的 data view，或网关账号缺少 Kibana Discover 权限（见 Elasticsearch 账号权限） |
feedback_persist_failed、save_failed、persist_failed | 反馈或数据写入失败（params.reason） |
| 错误码 | 含义 | 处理 |
|---|
alert_webhook_disabled | 告警 Webhook 推送未开启 | 设置 RST_ALERT_WEBHOOK_SECRET |
alert_webhook_token_invalid | X-RST-Alert-Token 不正确 | 核对 Kibana 连接器的请求头 |
alert_not_found、notify_target_not_found | 告警或通知目标不存在 | 无 |
push_failed | 投递失败（params.reason） | 查看投递记录 |
delivery_not_retryable | 该投递不能重投（不存在，或仍在队列或发送中） | 无 |
webhook_url_required、webhook_must_be_https、webhook_host_invalid、dingtalk_path_invalid、feishu_url_must_be_https、feishu_host_not_allowed、feishu_path_invalid、slack_path_invalid、wecom_key_missing | 机器人 Webhook 地址为空或格式不正确 | 从群机器人设置中原样复制 |
smtp_host_required、smtp_port_not_int、smtp_port_out_of_range、smtp_security_invalid、smtp_from_invalid | 发件服务器配置不正确，端口须为 1 到 65535 的整数 | 无 |
recipients_required、recipient_invalid | 收件人为空或地址不合法 | 无 |
| 错误码 | 含义 |
|---|
start_after_end | start 必须早于 end |
periods_not_array、unknown_period | 周期必须是数组，且取值在可选范围内 |
name_required | 名称为空 |
unknown_channel | 渠道不在可选范围内 |
severity_threshold_invalid | 告警严重度阈值不合法 |
hour_not_int、hour_out_of_range | 发送小时必须是 0 到 23 的整数 |
| 错误码 | 含义 |
|---|
masking_mode_unavailable | 脱敏档位不合法（params.choices） |
es_url_not_string、es_url_invalid | Elasticsearch 地址不是以 http:// 或 https:// 开头的完整地址 |
syslog_url_invalid | syslog 地址不合法（支持的 scheme 见 params.schemes） |
audit_webhook_url_invalid | 审计转发地址不是以 http:// 或 https:// 开头的完整 URL |
audit_webhook_host_not_allowed | 审计转发目标不在 RST_AUDIT_WEBHOOK_ALLOWLIST 中 |
audit_webhook_host_refused、audit_webhook_host_link_local | 审计转发不能指向该主机，包括回环和链路本地地址（169.254.169.254 是云实例元数据端点，不是 SIEM） |
| 错误码 | 含义 |
|---|
content_pack_rejected | 内容包未通过验签、版本或兼容性检查（params.reason） |
content_pack_apply_failed | 内容包应用时服务端出错 |
no_release_to_download | 当前没有可下载的新版本 |
release_download_failed、release_download_server_error | 新版本下载或暂存失败 |
rollback_failed、rollback_server_error | 回滚失败 |
import_failed、csv_import_failed、csv_text_missing | 导入失败，或请求中缺少 CSV 文本 |
| 错误码 | 含义 |
|---|
rule_id_invalid | 规则 ID 须为 3 到 64 位字母、数字或 . _ - |
rule_title_required | 规则标题为空 |
rule_query_required | 采集查询（osquery SQL）为空 |
rule_judge_missing | 缺少判据 |
rule_needs_field、rule_needs_expected | 该算子需要判定字段或期望值 |
rule_eol_needs_query | eol 算子需要采集 OS 版本的查询 |
rule_operator_invalid、rule_severity_invalid | 算子或严重度不合法 |
rule_shape_invalid、body_not_object | 规则结构不合法，或请求体不是 JSON 对象 |
baseline_rule_not_found | 规则不存在或删除失败 |
以下错误码表示 API 请求本身不完整或越界，通过界面操作时一般不会出现。
| 错误码 | 含义 |
|---|
body_empty、body_not_json | 请求体为空或不是合法 JSON |
doc_empty、dsl_empty、alert_empty、investigation_empty、cluster_empty、markdown_empty、question_empty、query_empty、title_empty、content_empty | 对应字段为空 |
index_required、doc_id_required、panels_required、content_token_required | 缺少必填字段 |
alerts_not_list | alerts 必须是数组 |
size_out_of_range、limit_out_of_range、top_k_out_of_range | 参数超出范围，分别为 1 到 500、1 到 200、1 到 50 |
offset_negative | offset 不能小于 0 |
state_kind_unknown | 状态类型不在可选范围内 |
invalid_time | 时间值不合法 |
invalid_request | 其他请求错误（params.reason） |
