错误语义

Dash API 错误格式：

{ "code": "<string>", "message": "<string>" }

通用

HTTP	code	说明
400	invalid_request	请求格式或字段非法
400	invalid_id	路径 ID 非法
400	no_fields	PATCH 没有可更新字段
401	unauthorized	鉴权失败
403	forbidden	已识别请求但无权限
404	not_found	资源不存在
409	conflict code	状态冲突
413	body_too_large	请求体过大
429	rate_limited	登录请求超过限流窗口
503	db_error	数据库读写失败
503	redis_cache_error	Redis 前台缓存同步失败

认证

HTTP	code	说明
400	invalid_json	登录请求体不是合法 JSON
400	invalid_persistence	登录 persistence 不是 session 或 persistent
400	invalid_session	会话 ID 为空
500	auth_error	认证操作失败
503	auth_unavailable	会话存储暂时不可用

节点管理

code	说明
invalid_name	节点名不满足 1～64 字符或含控制字符
invalid_display_order	排序值不是正数
invalid_traffic_cycle_mode	节点账期模式非法
invalid_traffic_cycle_settings	节点账期字段与账期模式不匹配
invalid_traffic_billing_start_day	账期日不在 1..31
invalid_traffic_billing_anchor_date	锚点日期非法
invalid_traffic_billing_timezone	时区非法
invalid_traffic_direction_mode	节点统计方向非法
invalid_tags	tags 非法、超过 32 项或单项超过 64 字符
invalid_secret	节点 secret 不满足 8～128 字符
duplicate_secret	节点 secret 已属于其他节点
invalid_group_ids	分组 ID 非法
secret_collision_exhausted	secret 随机冲突重试耗尽
secret_generation_failed	secret 生成失败

节点升级

HTTP	code	说明
409	node_version_unavailable	打包节点版本不可用
409	invalid_node_version	打包节点版本非法
409	node_upgrade_unsupported	当前节点版本低于 0.2.3，不支持自动下发更新
409	node_platform_unknown	节点平台未知
409	node_platform_unsupported	节点平台不支持
409	node_asset_missing	对应节点资产缺失
503	node_asset_error	生成升级资产失败
503	node_upgrade_grant_error	生成旧 Node 临时下载授权失败

流量

HTTP	code	说明
400	invalid_fields	流量设置字段非法
400	billing_cycle_is_per_node	全局设置提交了仅允许按节点修改的账期字段
409	traffic_daily_requires_billing	日统计要求 billing 模式
409	traffic_rebuild_requires_billing	手工重建要求 billing 模式
409	traffic_rebuild_running	已有流量重建任务运行中
503	traffic_rebuild_unavailable	流量重建任务不可用

告警和通知

code	说明
invalid_fields	规则、挂载、渠道或设置字段非法
not_logged_in	Telegram MTProto 未登录
login_state_error	Telegram MTProto 登录状态不可用
channel_changed	渠道配置 revision 已并发变化
notify_error	测试通知发送失败

主题

HTTP	code	说明
400	invalid_theme_package	主题包格式非法
404	not_found	主题不存在
500	theme_storage_unavailable	主题目录读取、写入或删除失败
500	theme_unavailable	内置主题目录不可用
503	theme_unavailable	当前主题无法校验

主题列表可能返回 warning header：

• theme_active_missing
• theme_active_broken

Dash 更新

HTTP	code	说明
400	invalid_fields	更新 action、channel、lang 或计划字段非法
409	dash_update_current	普通更新的目标等于当前版本；需要显式重装
502	dash_update_check_failed	发布源检查失败或超时
503	dash_update_failed	更新任务准备或启动失败
503	dash_update_unavailable	当前安装布局或恢复状态不允许受管更新

已有任务运行时，POST /api/admin/system/dash-update/run 返回 409 和当前状态资源，不返回 JSON 错误包装。

任务终态的 failure_code 还可能为 install_changed、recovery_required 或 rolled_back。这些值位于状态资源中，不是 HTTP 错误包装的 code。