Error codes

Most errors the UI or the API returns carry a code. Each code's HTTP status, meaning and remedy by area, plus a few common messages that have no code.

Error responses have the form {"detail": "<message>", "code": "<code>", "params": {...}}. The UI shows the message in the current language, API clients branch on code, and the values in params fill in the message.

Raw errors from Zabbix and from the model go to the server log only, never into the response. For details, run docker compose -f docker-compose.prod.yml logs gateway.

Code	HTTP	Meaning	Remedy
`login_required`	401	Not signed in, or the session expired	Sign in again
`permission_denied`	403	The current role (`params.role`) lacks the permission `params.permission`	Ask an administrator to adjust Role permissions in Settings
`admin_session_or_token_required`	403	An admin action with no valid session and no `X-RST-Admin-Token`	Sign in again, or send `RST_ADMIN_TOKEN` from ops scripts
`setting_locked_by_env`	409	The setting `params.key` is pinned by the environment variable `params.env`	Change it in `.env` and recreate the container
`eula_not_accepted`	403	This account has not accepted this version of the license agreement (`params.version`)	Read and accept it
`rate_limited`	429	Too many requests	Wait `params.seconds` seconds; limits are set with `RST_RATELIMIT_*`

License

Code	HTTP	Meaning	Remedy
`feature_needs_standard`	403	`params.feature` needs Professional or Enterprise. Possible values: `alert_triage` (alert correlation), `alert_investigation` (fault investigation, remote ping and traceroute), `detection_rule_copilot` (triggers and monitoring config, maintenance-window assistant), `platform_ops_copilot` (platform checkup)	Activate a license; see Editions
`reports_need_professional`	403	Reports, scheduled reports and inspections need Professional or Enterprise	Activate a license
`feature_needs_enterprise`	403	`params.feature` needs Enterprise. Possible values: `sso_oidc` (SSO, auditor role), `offline_issuance` (offline activation)	Activate an Enterprise license; Professional licenses activate online
`feature_sealed`	403	No valid license, or the license lacks the feature key for this feature	Activate a license that includes it; if an offline license lacks the key, ask us to reissue it
`license_invalid`	403	License verification failed (signature, decryption or tampering); everything except sign-in, the license agreement and the License page is refused	Ask sales to reissue it
`license_status_abnormal`	403	The license is in an unexpected state	Check the License page
`users_need_professional`	403	Community Edition has one user; returned when creating or enabling an account, and the UI shows an upgrade dialog	Activate a Professional or Enterprise license
`user_seats_exhausted`	403	All `params.seats` user seats on the license are in use; returned when creating or enabling an account	Disable an account, or buy more seats
`seats_exceeded_admin_only`	403	More accounts are enabled than the `params.seats` seats of the current license (expired, revoked, or fewer seats); returned to non-admins on sign-in or on any request	An admin renews the license, or disables extra accounts on the Users page
`machine_id_unreadable`	503	Cannot read this machine's hardware identity (`params.reason`)	Check that `state/machine-id` exists and is mounted as `/etc/machine-id`
`license_deactivate_error`	500	Deactivation failed (`params.reason`)	Act on the reason

Zabbix

Code	HTTP	Meaning	Remedy
`zabbix_unreachable`	502	Cannot reach the Zabbix API	Check `ZABBIX_URL`, the network and the certificate
`zabbix_auth_failed`	Connection test result	The API token or username / password is invalid	Replace the credentials; see Zabbix permissions
`zabbix_request_failed`	Connection test result	The Zabbix API returned an error (`params.reason` is Zabbix's own text)	Act on the reason
`zabbix_not_api`	400	The address is not a Zabbix JSON-RPC endpoint	Use an address ending in `/api_jsonrpc.php`
`zabbix_url_invalid`	400	Not an http(s) URL, or it contains a username and password	Use `https://<host>/api_jsonrpc.php`
`zabbix_version_unsupported`	502	The Zabbix version (`params.version`) is below 6.0	Upgrade Zabbix; 6.0, 6.4, 7.0, 7.2 and 7.4 are verified
`zabbix_query_failed`	502	A Zabbix query failed	Search the gateway log for `zabbix_call_failed`
`zabbix_call_rejected`, `zabbix_call_rejected_repair_failed`	400	Zabbix rejected the generated API call and auto-repair did not help	Expand the API call in the chat, edit it and retry, or rephrase the question
`secret_reentry_required`	400	The connection address changed; stored credentials are not sent to a new address	Enter the token, password or API key again
`index_not_whitelisted`	403	Host group `params.index` is outside the host group allowlist (`params.patterns`)	An administrator adds it to Host group allowlist in Settings
`hosts_not_whitelisted`	403	Some hosts are outside the host group allowlist	Same as above
`group_required_by_whitelist`	400	A host group allowlist is active and the request named no host group	Choose a host group
`host_group_not_found`	404	Zabbix has no host group `params.group`	Check the name
`host_not_found`, `host_not_in_topology`	404	Host `params.hostid` does not exist, or is not in the topology	None
`hostid_not_numeric`, `hostid_or_group_required`, `too_many_hosts`	400	hostid is not numeric; no hostid or host group given; more than `params.limit` hosts at once	Fix the request
`maintenance_not_found`	404	Maintenance `params.id` does not exist or was deleted	None
`maintenance_not_managed`	403	Maintenance `params.name` was not created by this product	Delete it in Zabbix
`maintenance_out_of_scope`	403	The maintenance covers hosts or host groups outside the host group allowlist	Handle it in Zabbix
`diagnostics_script_scope_invalid`	403	The Zabbix script `params.script` does not have the scope "Manual host action"	Change the script's scope in Zabbix

Models and knowledge base

Code	HTTP	Meaning	Remedy
`llm_timeout`	504	The model call timed out	Retry later, or raise the timeout in AI settings
`llm_unavailable`	503	Every enabled provider failed	Check the provider settings and the network path to the model endpoint
`llm_unparseable`	502	The model's output could not be parsed	Retry
`llm_request_failed`	502	Any other model call failure	Search the gateway log for `llm_call_failed`
`model_required`	400	No model name given	Fill it in
`connection_test_failed`	400	The connection test failed (`params.reason`)	Act on the reason
`kb_dim_mismatch`	409	The knowledge base was built with `params.index_dims`-dimension vectors; the current model has `params.real_dims`	Switch back to the original embedding model, or delete the knowledge base documents and upload them again

Feature calls

Code	HTTP	Meaning
`alerts_aggregate_failed`	502	Alert statistics failed (`params.reason`)
`platform_checkup_failed`	500	The platform checkup failed; see the gateway log
`nothing_to_explain`	400	The query returned no rows, so there is nothing to interpret
`invalid_time`	400	`params.what` is not a valid time (`params.value`)
`dsl_empty`, `cluster_empty`, `investigation_empty`, `markdown_empty`	400	The request has no Zabbix API call, alert cluster, investigation or body text
`body_not_object`	400	The request body is not a JSON object

Outbound channels

Code	HTTP	Meaning	Remedy
`push_failed`	500	Delivery failed (`params.reason`)	Check the delivery log
`delivery_not_retryable`	409	The delivery does not exist, or is queued or in flight	None
`notify_target_not_found`	404	The target does not exist	None
`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	The bot address is empty or malformed	Copy it unchanged from the group bot settings
`smtp_host_required`, `smtp_port_not_int`, `smtp_port_out_of_range`, `smtp_security_invalid`, `smtp_from_invalid`	400	Mail server settings are malformed	Fix the settings
`recipients_required`, `recipient_invalid`	400	No recipients, or a malformed address	Fix the settings
`unknown_channel`, `unknown_period`, `periods_not_array`, `hour_not_int`, `hour_out_of_range`, `severity_threshold_invalid`, `name_required`	400	Invalid channel, schedule or name	Fix the settings
`egress_metadata_refused`	400	`params.value` is a cloud metadata address; no channel may post there	Use another address
`egress_entry_invalid`, `egress_too_many`	400	An extra address is not a valid host name, IP or CIDR; at most `params.limit` per channel	Fix the settings

Content packs and online update

Code	HTTP	Meaning	Remedy
`content_token_required`	400	No content pack token in the request	Paste the signed content pack token
`content_pack_rejected`	400	Bad signature, older than the active version, or incompatible (`params.reason`)	Check where the token came from and its version
`content_pack_apply_failed`	500	Server error while applying the pack	Check the gateway log
`no_release_to_download`	400	There is no new version to download	Choose Check now first
`release_download_failed`	400	Download or staging failed: bad signature, not enough disk, or an updater that is too old (`params.reason`)	Act on the reason
`release_download_server_error`	500	Server error during download	Check the gateway log
`rollback_failed`, `rollback_server_error`	400, 500	Content pack rollback failed	Act on the reason

Messages without a code

These messages have no code and only a Chinese text, so the English UI shows them in Chinese.

Message (meaning)	HTTP	Remedy
请先登录。 (sign in first)	401	Sign in again
用户名或密码错误。 (wrong username or password)	401	None
登录失败次数过多，请稍后再试。 (too many failed sign-ins)	429	Retry after 5 minutes
该账号仍在使用出厂默认密码，禁止远程登录。 (factory password, remote sign-in refused)	403	Set `RST_ADMIN_PASSWORD_HASH`, or sign in on the host and change the password
跨站请求被拒绝（Origin 与本站不一致）。 (cross-site request refused)	403	Act from the product page itself
License 激活失败：… (activation failed)	400	The reason follows the colon; see the FAQ
License 激活异常：… (activation error)	500	Check the gateway log

On this page