Error Semantics

Dash API error format:

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

Common

HTTP	code	Description
400	invalid_request	Invalid request shape or fields
400	invalid_id	Invalid path ID
400	no_fields	PATCH request has no updatable fields
401	unauthorized	Authentication failed
403	forbidden	Request is recognized but not allowed
404	not_found	Resource does not exist
409	conflict code	State conflict
413	body_too_large	Request body is too large
429	rate_limited	Login requests exceeded the rate-limit window
503	db_error	Database read or write failed
503	redis_cache_error	Redis cache sync failed

Authentication

HTTP	code	Description
400	invalid_json	Login request body is not valid JSON
400	invalid_persistence	Login persistence is not session or persistent
400	invalid_session	Session ID is empty
500	auth_error	Authentication operation failed
503	auth_unavailable	Session storage is temporarily unavailable

Node Management

code	Description
invalid_name	Node name is outside 1–64 characters or contains control characters
invalid_display_order	Display order is not positive
invalid_traffic_cycle_mode	Invalid node billing cycle mode
invalid_traffic_cycle_settings	Node billing cycle fields do not match the selected mode
invalid_traffic_billing_start_day	Billing day is outside 1..31
invalid_traffic_billing_anchor_date	Invalid billing anchor date
invalid_traffic_billing_timezone	Invalid billing timezone
invalid_traffic_direction_mode	Invalid node traffic direction mode
invalid_tags	Invalid tags, more than 32 items, or an item over 64 characters
invalid_secret	Node secret is outside 8–128 characters
duplicate_secret	Node secret already belongs to another node
invalid_group_ids	Invalid group IDs
secret_collision_exhausted	Random secret collision retries exhausted
secret_generation_failed	Secret generation failed

Node Upgrade

HTTP	code	Description
409	node_version_unavailable	Bundled node version is unavailable
409	invalid_node_version	Bundled node version is invalid
409	node_upgrade_unsupported	Current node version is below 0.2.3 and does not support automatic update delivery
409	node_platform_unknown	Node platform is unknown
409	node_platform_unsupported	Node platform is unsupported
409	node_asset_missing	Matching node asset is missing
503	node_asset_error	Upgrade asset generation failed
503	node_upgrade_grant_error	Legacy temporary download grant generation failed

Traffic

HTTP	code	Description
400	invalid_fields	Invalid traffic settings field
400	billing_cycle_is_per_node	A global settings request includes per-node cycle fields
409	traffic_daily_requires_billing	Daily traffic requires billing mode
409	traffic_rebuild_requires_billing	Manual rebuild requires billing mode
409	traffic_rebuild_running	A traffic rebuild task is already running
503	traffic_rebuild_unavailable	Traffic rebuild is unavailable

Alerts and Notifications

code	Description
invalid_fields	Invalid rule, mount, channel, or setting fields
not_logged_in	Telegram MTProto is not logged in
login_state_error	Telegram MTProto login state is unavailable
channel_changed	Channel config revision changed concurrently
notify_error	Test notification send failed

Themes

HTTP	code	Description
400	invalid_theme_package	Invalid theme package format
404	not_found	Theme does not exist
500	theme_storage_unavailable	Theme directory read, write, or deletion failed
500	theme_unavailable	Built-in theme catalog is unavailable
503	theme_unavailable	Active theme validation is unavailable

Theme lists can return theme_active_missing or theme_active_broken warning states.

Dash Update

HTTP	code	Description
400	invalid_fields	Invalid update action, channel, language, or plan fields
409	dash_update_current	A normal update target equals the current version
502	dash_update_check_failed	Release-source check failed or timed out
503	dash_update_failed	Update preparation or task start failed
503	dash_update_unavailable	Install layout or recovery state prevents managed update

When a task is already running, POST /api/admin/system/dash-update/run returns 409 with the current status resource rather than a JSON error wrapper.

Task failure_code may include install_changed, recovery_required, or rolled_back; these are status fields, not HTTP error wrapper codes.