错误码
界面和 API 返回的每个错误都带一个 code。按分类列出每个码的含义和处理方法。
网关的错误响应为 {"detail": "<中文说明>", "code": "<错误码>", "params": {...}}。界面按当前语言显示说明，API 调用方按 code 判断，params 中的值填入说明。
| 错误码 | 含义 | 处理 |
|---|
login_required | 未登录或会话过期 | 重新登录 |
bad_credentials | 账号或密码错误 | 无 |
login_throttled | 登录失败次数过多 | 5 分钟后重试 |
default_password_refused | 仍在使用出厂密码，拒绝远程登录 | 设置 RST_ADMIN_PASSWORD_HASH。局域网试验可设 RST_ALLOW_DEFAULT_PASSWORD=1 |
password_login_disabled | 已启用 SSO，密码登录关闭 | 从 SSO 入口登录 |
read_only | 只读角色不能修改 | 联系管理员 |
admin_role_required、admin_login_required、admin_session_or_token_required | 当前身份没有管理权限 | 以管理员登录，或运维调用携带 X-RST-Admin-Token |
admin_group_required | SSO：不在 RST_RBAC_ADMIN_GROUPS 的组中 | 由 IdP 管理员加组 |
sso_identity_required | 已启用 SSO 但请求没有已验证身份 | 从 SSO 入口登录。检查 oauth2-proxy |
csrf_rejected | 跨站请求被拒绝 | 从产品页面本身操作 |
rate_limited | 触发限速 | 等待 params.seconds 秒。多人共用出口 IP 时调整 RST_RATELIMIT_* |
user_db_not_configured、password_in_env_only | 未配置用户表。单账号部署的密码在 .env 中 | 设置 RST_USER_DB_URL，或按提示重新生成哈希 |
user_exists、user_not_found、unknown_role、username_required | 用户管理的参数问题 | 无 |
last_admin_locked、last_admin_undeletable | 最后一个管理员不能停用、降级或删除 | 先创建另一个管理员 |
cannot_disable_self、cannot_delete_self | 不能停用或删除自己 | 无 |
password_too_short、password_min_length、current_password_wrong | 密码少于 8 位。当前密码错误 | 无 |
password_change_not_supported | SSO 账号不能在此修改密码 | 在 IdP 修改 |
| 错误码 | 含义 | 处理 |
|---|
feature_needs_standard、incident_report_needs_standard、platform_checkup_needs_standard | params.feature 需要专业版及以上 | 激活许可 |
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 | 读不到硬件标识 | 检查 /etc/machine-id 挂载 |
license_activate_failed、license_activate_error、license_deactivate_error | 激活或撤销被拒绝或异常（params.reason：名额用完、指纹不符、不属于本产品等） | 按原因处理 |
| 错误码 | 含义 | 处理 |
|---|
qradar_not_configured | 未填写 Console 地址或 Token | 在系统设置填写 |
qradar_url_invalid、qradar_url_not_string | Console 地址不是完整的 http(s) URL | 无 |
qradar_unreachable | 无法连接 Console | 检查 QRADAR_URL、443 连通性、证书校验 |
qradar_auth_failed | 401，SEC Token 无效或过期 | 更换 Token |
qradar_forbidden | 403，Token 的用户角色没有这个接口的权限（params.reason） | 见 QRadar Token 权限 |
qradar_timeout | Ariel 搜索超过 params.seconds 秒被取消 | 缩小时间窗或增加日志源条件。调整 RST_AQL_TIMEOUT_SECONDS |
qradar_aql_error | AQL 被 QRadar 拒绝（params.reason 是 Console 原文） | 展开 AQL 修改，或选择让 AI 带着报错重修 |
qradar_search_failed、qradar_request_failed | Ariel 搜索或其他请求失败（params.reason） | 按原因处理 |
alert_not_found、offense_not_found、offense_update_failed | Offense 不存在。关闭、备注、分配写回失败（params.reason） | 关闭失败通常是 Token 缺少 Offense 写权限，或已被其他人关闭 |
rule_not_found | 规则不存在 | 无 |
| 错误码 | 含义 | 处理 |
|---|
aql_empty | 请求中没有 AQL | 无 |
aql_not_select | 只允许 SELECT | 修改语句 |
aql_multiple_statements | 一次只允许一条语句 | 去掉分号后的部分 |
aql_bad_source | 只能查询 events 或 flows，不能查询 params.source | 无 |
aql_validation_failed | 其他只读校验失败（params.reason） | 修改语句 |
log_source_not_whitelisted | 引用了白名单外的日志源 params.name（白名单 params.patterns）。reason=unbounded 表示无法自动限定：子查询、目录不可用、或白名单展开超过 50 个 | 在系统设置添加日志源，或在 AQL 中限定 LOGSOURCENAME() |
| 错误码 | 含义 | 处理 |
|---|
llm_generation_failed | 模型调用失败（params.reason） | 查看 AI 配置中 provider 的状态 |
llm_timeout | 模型调用超时 | 提高 provider 超时。减少送模型的聚类数 |
llm_first_token_timeout | params.limit_s 秒内未开始作答，已中止 | 换一种问法重试。调低推理强度 |
providers_empty、model_required | provider 列表为空或未填模型 | 至少配置一个 |
connection_test_failed | 测试连接失败（params.reason） | 按原因处理 |
| 错误码 | 含义 |
|---|
investigation_failed、triage_failed、detection_rule_failed、report_generation_failed、incident_report_failed、platform_checkup_failed、suggest_angles_failed | 对应功能失败，params.reason 含细节 |
detection_rule_rejected | 模型拒绝生成，意图不明确 |
too_many_alerts | 一次分诊最多 params.cap 条 |
alert_empty、cluster_empty、investigation_empty、incident_input_required | 请求中没有 Offense、簇或调查结果 |
conversation_not_found、analysis_record_not_found | 会话或记录不存在或已过期 |
explain_log_failed、explain_result_failed、nothing_to_explain、alerts_aggregate_failed | 解读失败。没有可解读的结果。告警概览聚合失败 |
question_empty、query_empty、doc_empty、alerts_not_list、feedback_persist_failed | 请求缺少问题、AQL 或事件。alerts 不是数组。反馈未保存 |
size_out_of_range、limit_out_of_range、top_k_out_of_range、offset_negative、invalid_time、start_after_end | 参数超范围或时间不合法 |
| 错误码 | 含义 | 处理 |
|---|
push_failed | 投递失败（params.reason） | 查看投递记录 |
delivery_not_retryable、notify_target_not_found | 该投递不能重投。目标不存在 | 无 |
webhook_must_be_https、webhook_host_invalid、webhook_url_required、feishu_url_must_be_https、feishu_host_not_allowed、feishu_path_invalid、dingtalk_path_invalid、wecom_key_missing、slack_path_invalid | 机器人地址格式不正确 | 从群机器人设置中原样复制 |
smtp_host_required、smtp_port_out_of_range、smtp_port_not_int、smtp_security_invalid、smtp_from_invalid | 发件服务器配置格式错误 | 无 |
recipients_required、recipient_invalid | 收件人为空或格式错误 | 无 |
unknown_channel、unknown_period、periods_not_array、hour_not_int、hour_out_of_range、severity_threshold_invalid | 排期参数不合法 | 无 |
| 错误码 | 含义 |
|---|
masking_mode_unavailable | 脱敏档位不合法（params.choices） |
audit_webhook_url_invalid、audit_webhook_host_not_allowed、audit_webhook_host_refused | 审计转发目标格式错误、不在 RST_AUDIT_WEBHOOK_ALLOWLIST、或指向回环与链路本地地址 |
audit_webhook_host_link_local | 169.254.169.254 是云实例元数据，不是 SIEM |
syslog_url_invalid | syslog 地址格式错误 |
content_pack_rejected、content_pack_apply_failed、release_download_failed、release_download_server_error、no_release_to_download、rollback_failed、rollback_server_error | 内容包或在线更新的验签、下载或回滚失败 |
body_not_json、body_empty、body_not_object、invalid_request、state_kind_unknown、name_required、title_empty、content_empty、markdown_empty、doc_id_required、panels_required、csv_text_missing | 请求体格式或必填字段问题 |
content_token_required、import_failed、failed_case_not_found、persist_failed、save_failed、metrics_token_required | 内容包 token 缺失。导入失败。评测用例不存在。落盘失败。/metrics 缺令牌 |
