Skip to content

接口错误码 ​

错误响应的结构 ​

控制面拒绝请求时,返回的正文是 JSON:

json
{"detail": "单次最多上报 100 条事件。", "code": "EVENT_BATCH_TOO_LARGE", "message": "单次最多上报 100 条事件。", "params": {"max": 100}}
字段含义
code稳定的代码,全大写加下划线。只增加,不改名。按它和 HTTP 状态码决定怎么处理
message和 detail 同一句话,按请求的语言写
detail字符串。请求校验错误(REQUEST_INVALID)例外,是问题列表,每一项只有 type、loc 和 msg,从不带提交的值
params句子里有数值时才出现。只放标量,从不放密钥

用 X-Guard-Locale: zh 或 X-Guard-Locale: en 选择语言。/v1/ 的响应带 Content-Language。不带这个请求头时,得到的是旧版中文措辞,为旧客户端保持不变。

策略编辑器的校验错误(POLICY_DSL_INVALID,422)另有 errors[],每个问题一项,带 line、column、path、message、code 和 params。DSL_* 就是这些项的代码。

不是控制面自己返回的响应(代理的 502、网关超时、不是 JSON 的正文)没有 code,按状态码处理。

SDK 把 401 和 403 当作认证错误,从不退回去用缓存的策略。SDK 不发送语言请求头。

判定的原因码 ​

这些不是 HTTP 错误,而是判定结果里的 reason_code,出现在事件里,也出现在模型看到的内容里。

原因码含义
ALLOWED符合策略
DEFAULT_DENY不在已批准的范围内(默认拒绝)
RULE_DENIED命中拒绝规则
APPROVAL_REQUIRED命中需审批规则
APPROVED已批准一次执行
DEGRADED命中降级规则
POLICY_EXPIRED策略已过期
SUBJECT_REQUIRED缺少可信主体
POLICY_CHANGED策略已更新,需按新策略重新发起
APPROVAL_NOT_CONSUMABLE审批票据已不可用
GUARD_UNAVAILABLE 及其他 GUARD_*Guard 无法判定,工具没有执行
FALLBACK_*替代工具不可用或未被放行
MCP_*在 MCP 边界被拒绝
HTTP_*在网络出口被拒绝

原因码 HTTP_* 和错误响应里的 code(比如 HTTP_404)不是一回事。

错误码 ​

所有接口 ​

代码状态说明
REQUEST_INVALID422请求字段不符合要求:{fields}。
UNCLASSIFIED_CONFLICT409
HTTP_ERROR4xx / 5xx请求没有完成(HTTP {status})。
CROSS_SITE_REQUEST_REFUSED403跨站请求被拒绝。
RECORD_NOT_FOUND404记录不存在或不属于当前身份。
SUBJECT_ID_REQUIRED409可信主体 ID 不能为空。

令牌、角色、会话与企业账号登录 ​

代码状态说明
RUNTIME_TOKEN_REQUIRED401需要项目令牌或执行器凭据。
RUNTIME_TOKEN_INVALID401项目令牌或执行器凭据无效、已过期或已撤销。
TOKEN_NOT_POLICY_ADMIN403当前令牌没有策略管理权限。
TOKEN_NOT_OWNER403只有项目所有者可以管理项目令牌。
EXECUTOR_TOKEN_CANNOT_READ403执行器凭据不能读取控制操作审计和策略管理记录。
TOKEN_NOT_EXECUTOR403当前令牌不能上报执行器事件。
MANAGED_GATEWAY_NEEDS_ENFORCE503云托管网关需要强制执行模式的策略。
TOKEN_NOT_REVIEWER403只有独立审核员的令牌可以审核策略。
NAMED_SIGN_IN_REQUIRED401请用具名账号登录。
SESSION_CSRF_INVALID403会话校验未通过,请重新登录。
ACCOUNT_CANNOT_REVIEW_ACTIONS403当前账号不能处理动作审批。
ACCOUNT_NOT_POLICY_ADMIN403当前账号没有策略管理权限。
ACCOUNT_OWNER_MANAGES403只有项目所有者可以管理具名账号。
ACCOUNT_OWNER_VIEWS403只有项目所有者可以查看具名账号。
POLICY_REVIEW_NEEDS_REVIEWER403只有独立审核员可以批准或驳回候选策略。
SSO_NOT_CONFIGURED404未配置企业账号登录。
SSO_UNAVAILABLE429企业账号登录暂不可用,请稍后再试。
SSO_INCOMPLETE401企业账号登录没有完成,请重新登录。
SSO_FAILED401企业账号登录验证未通过,请重新登录。
SSO_SESSION_MISSING401还没有企业账号登录的会话,请重新登录。
SSO_PROJECT_UNKNOWN—(回 SSO_UNAVAILABLE)身份项目未注册。
SSO_CAPACITY_FULL—(回 SSO_UNAVAILABLE)身份登录容量已满。
SSO_LOGIN_EXPIRED—(回 SSO_FAILED)身份登录已失效。
SSO_ACCOUNT_DISABLED—(回 SSO_FAILED)身份账号已停用。

Yi Labs 账号登录、组织与成员 ​

代码状态说明
PREWORLD_NOT_CONFIGURED404(页面)这个 Guard 没有开启 Yi Labs 账号登录。
PREWORLD_LOGIN_EXPIRED400(页面)这次登录已过期或已经用过,请重新登录。
PREWORLD_ISSUER_MISMATCH400(页面)登录结果不是来自这个 Guard 配置的 Yi Labs 账号服务,已拒绝。请重新登录。
PREWORLD_LOGIN_CANCELED401(页面)已取消登录。
PREWORLD_LOGIN_FAILED401(页面)Yi Labs 账号登录没有通过验证,请重新登录。
PREWORLD_UNAVAILABLE503(页面)暂时连不上 Yi Labs 账号服务,请稍后再试。
PREWORLD_RATE_LIMITED429(页面)从这个网络发起的登录太多了,请过一分钟再试。
PREWORLD_ORG_NOT_LINKED403(页面)这个组织还没有可用的 Guard 空间。请让所有者先登录;预开通的空间请用登记邮箱认领,过期或解绑后请联系支持。也可以切换组织或新建自己的组织。
PREWORLD_ORG_ALREADY_LINKED409(页面)这个组织已经连接过了,不能再连接。
PREWORLD_MEMBER_DISABLED403 / 403(页面)你在这个 Guard 组织里已被停用,请联系所有者。
PREWORLD_NO_PROJECT403(页面)这个组织在 Guard 里没有可以打开的项目。
PREWORLD_ORG_OWNER_REQUIRED403只有当前组织的所有者可以创建项目。
PREWORLD_PROJECT_REQUEST_CONFLICT409这次创建请求已用于另一个项目名称,或该项目已停用。请刷新后再试。
PREWORLD_PROJECT_LIMIT409这个组织已达到 100 个项目的创建上限,请联系支持。
PREWORLD_PROJECT_UNKNOWN404这个项目不在你登录的组织里。
PREWORLD_MEMBER_EXISTS409这个邮箱已经是项目成员。
PREWORLD_MEMBER_ROLE_FROM_PREWORLD409这个成员是组织的所有者,在 Yi Labs 账号里管理,不能在这里修改角色或停用。

开通项目(自部署) ​

代码状态说明
ONBOARDING_DISABLED403项目开通已关闭。
ONBOARDING_NOT_CONFIGURED503尚未配置初始化密钥。
ONBOARDING_KEY_INVALID403初始化密钥无效。
ONBOARDING_NAMES_REQUIRED422组织和项目名称不能为空。

执行器、事件与项目令牌 ​

代码状态说明
AGENT_CREDENTIAL_MISMATCH403Agent 与执行器凭据不匹配。
EXECUTOR_NOT_FOUND404执行器不存在。
EXECUTOR_V2_REQUIRED409当前策略是格式 v2,执行器需要支持格式 v2。
POLICY_ACK_INCOMPLETE409策略确认须同时包含版本和摘要。
POLICY_ACK_UNKNOWN409执行器报告的策略版本或摘要不存在。
EXECUTOR_STATUS_INVALID409执行器状态无效。
TOKEN_ALREADY_INVALID409当前令牌已经失效。
PROJECT_TOKEN_NOT_FOUND404项目令牌不存在或已撤销。
AUDIT_CURSOR_NOT_FOUND404审计游标不存在或不属于当前项目。
EVENT_BATCH_TOO_LARGE413单次最多上报 {max} 条事件。
EVENT_AGENT_MISMATCH403事件里的 Agent 与执行器凭据不匹配。
EVENT_PROJECT_MISMATCH403事件里的项目与当前令牌不匹配。
EVENT_TENANT_MISMATCH403事件里的租户与当前令牌不匹配。
EVENT_ID_TAKEN409事件编号已经属于其他项目。
EVENT_CAPACITY_FULL409项目事件容量已满,请归档或调整容量。
EVENT_CURSOR_NOT_FOUND404事件游标不存在或不属于当前项目。
TOKEN_ROLE_INVALID409无效的项目令牌角色。
EVENT_FILTER_TIMEZONE409时间过滤条件须包含时区。
EVENT_FILTER_TIME_INVALID409时间过滤条件 {field} 不是有效的 ISO 8601 时间。
EVENT_FILTER_UNKNOWN409未知事件过滤条件。
SETTINGS_OUT_OF_RANGE409保留期或容量限额超出允许范围。
ARCHIVE_PURGE_TOO_MANY409每批归档最多清理 100 条。
ARCHIVE_PURGE_REFUSED409归档摘要不匹配或事件尚在保留期内。

成员角色与可信主体 ​

代码状态说明
ACCOUNT_ROLE_INVALID409无效的具名账号角色。
ACCOUNT_NOT_FOUND404具名账号不存在或已停用。
REVIEWER_SUBJECT_INVALID422具名账号的可信主体 ID 不能为空,也不能有首尾空白。
ACCOUNT_CANNOT_DISABLE_SELF409不能停用当前登录账号。

动作审批 ​

代码状态说明
APPROVAL_AGENT_MISMATCH403审批里的 Agent 与执行器凭据不匹配。
APPROVAL_PROJECT_MISMATCH403审批动作与执行器项目不匹配。
TICKET_NOT_FOUND404审批票据不存在。
APPROVAL_SUBJECT_REQUIRED422动作必须绑定有效可信主体 ID。
APPROVAL_PREVIEW_FIELDS422审批预览仅允许 summary、destination、data_labels;不得上传原始参数。
APPROVAL_PREVIEW_TEXT_TOO_LONG422审批预览文本必须短于 200 字符。
APPROVAL_PREVIEW_LABELS_INVALID422审批预览数据标签无效。
APPROVAL_PREVIEW_TOO_LARGE422审批预览过大。
APPROVAL_POLICY_CHANGED409审批动作的策略已变更,或不在强制执行模式。
APPROVAL_RULE_NOT_FOUND409当前策略没有匹配的需审批规则。
TICKET_DECISION_INVALID409无效审批结果。
TICKET_ALREADY_DECIDED409审批票据已处理或已过期。
TICKET_SELF_APPROVAL409动作发起人不能审批自己的动作。
TICKET_POLICY_CHANGED409审批票据对应的策略已变更。
TICKET_DECIDED_ELSEWHERE409审批票据已由他人处理。
TICKET_MISMATCH409审批票据与当前动作或执行器不匹配。
TICKET_NOT_USABLE409审批票据尚未批准、已过期或已使用。
TICKET_USED_ELSEWHERE409审批票据已由其他执行器使用。
TICKET_CANNOT_CANCEL409当前票据无法取消。

策略、审核、发布与回滚 ​

代码状态说明
CANDIDATE_NOT_FOUND404候选策略不存在。
CANDIDATE_MODE_INVALID409无效的候选策略模式。
OBSERVATION_WINDOW_NOT_POSITIVE409观察窗口和最小出现次数必须为正数。
PREVIEW_BASIS_INVALID409预演口径无效:只能是 attempted(全部尝试过的动作)或 completed(仅已完成的动作)。
OBSERVATION_WINDOW_INVALID422观察窗口参数超出范围。
CANDIDATE_TTL_INVALID422候选策略有效期必须在 1 到 720 小时之间。
PREVIEW_RANGE_INVALID422预演窗口或样本数超出范围。
CANDIDATE_NO_OBSERVED_ACTIONS409观察窗口内没有满足次数阈值的成功动作,不能生成空白允许清单。
REVIEW_COMMENT_TOO_LONG422审核说明不能超过 1000 字符。
POLICY_REVIEW_NOT_FOUND404独立审核记录不存在。
POLICY_VERSION_CONFLICT409运行时策略已更新,请刷新后再发布。
CANDIDATE_NOT_APPROVED409候选策略必须先通过独立审核。
POLICY_REVIEW_MISMATCH409独立审核记录与候选策略不匹配,或还没有批准。
EVAL_FINDING_DIGEST_INVALID422Eval finding bundle 摘要校验失败。
EVAL_FINDING_CONFLICT409同一 finding_id 已经存在不同内容。
EVAL_FINDING_NOT_FOUND404Eval finding 不存在。
EVAL_FINDING_OTHER_PROJECT409finding_id 已经属于其他项目。
POLICY_DSL_INVALID422策略 DSL 无效:
POLICY_INVALID409 / 422策略无效:
POLICY_BODY_TOO_LARGE413策略请求超过 {kib} KiB。
POLICY_VERSION_INVALID422策略版本必须是正整数。
POLICY_VERSION_NOT_FOUND404策略版本不存在。
ROLLBACK_AUDIT_MISSING500回滚必须有控制审计记录。
ROLLBACK_TARGET_NOT_FOUND404目标策略版本不存在。
ROLLBACK_REASON_INVALID409回滚原因必须为 1 到 500 字符。
ROLLBACK_VERSION_CONFLICT409运行时策略已更新,请刷新后再回滚。
ROLLBACK_TARGET_NOT_EARLIER409回滚目标必须是更早的策略版本。
ROLLBACK_AUDIT_AMBIGUOUS409回滚缺少唯一的控制审计记录。
POLICY_V2_NEEDS_EXECUTORS409发布格式 v2 的策略前,项目里所有已注册的执行器都必须支持格式 v2。
CANDIDATE_NOT_APPROVED_OR_EXPIRED409候选策略必须先通过独立审核,并且尚未过期。
CANDIDATE_EXPIRED409候选策略已过期。
CANDIDATE_BASE_OUTDATED409候选策略基于 v{base} 起草,当前已是 v{current};请基于当前策略重新起草,再提交独立审核。
CANDIDATE_HASH_MISMATCH409要发布的策略与审核时的摘要不一致,没有发布。
CANDIDATE_STATUS_TRANSITION409候选策略不能从 {current} 转为 {target}。
POLICY_REVIEW_NEEDS_ACCOUNT409具名账号提交的独立审核必须绑定账号。
CANDIDATE_CANNOT_REQUEST_REVIEW409当前候选策略不能提交独立审核。
POLICY_REVIEW_DECISION_INVALID409独立审核的决定无效。
POLICY_REVIEW_DECISION_NEEDS_ACCOUNT409具名账号作出的审核决定必须绑定账号。
POLICY_REVIEW_SAME_SUBJECT409独立审核必须由另一位可信主体处理。
POLICY_REVIEW_ALREADY_DECIDED409独立审核已经完成,不能重复处理。
CANDIDATE_NOT_IN_REVIEW409候选策略已过期,或不在独立审核中。
POLICY_REVIEW_BY_AUTHOR409策略作者不能审核自己起草的候选策略,独立审核必须由另一位可信主体处理。

策略编辑器的诊断 ​

代码状态说明
DSL_YAML_ALIAS422(errors[] 里)不支持 YAML 别名(*alias),请直接写出内容。
DSL_YAML_ANCHOR422(errors[] 里)不支持 YAML 锚点(&anchor),请直接写出内容。
DSL_YAML_TAG422(errors[] 里)不支持 YAML 标签 {tag}。
DSL_TOO_MANY_NODES422(errors[] 里)策略节点超过 {max} 个。
DSL_TOO_DEEP422(errors[] 里)嵌套层级超过 {max} 层。
DSL_MULTIPLE_DOCUMENTS422(errors[] 里)只能包含一个 YAML 文档。
DSL_KEY_NOT_STRING422(errors[] 里)对象的键必须是字符串。
DSL_MERGE_KEY422(errors[] 里)不支持 YAML 合并键 <<。
DSL_DUPLICATE_KEY422(errors[] 里)重复的键 {key}。
DSL_SOURCE_TOO_LARGE422(errors[] 里)策略 DSL 超过 {kib} KiB。
DSL_YAML_SYNTAX422(errors[] 里)YAML 语法错误:
DSL_YAML_UNPARSABLE422(errors[] 里)YAML 无法解析:
DSL_DOCUMENT_TOO_LARGE422(errors[] 里)策略文档超过 {kib} KiB。
DSL_DOCUMENT_TOO_COMPLEX422(errors[] 里)策略文档的嵌套层级或节点数超出限制。
DSL_SOURCE_OR_DOCUMENT422(errors[] 里)请只提供 source(YAML 文本)或 document(JSON 对象)之一。
DSL_NOT_A_MAPPING422(errors[] 里)运行时策略文档必须是 YAML 对象。
DSL_INVALID422(errors[] 里)策略文档无效。
DSL_FIELD_MISSING422(errors[] 里)缺少必填字段。
DSL_FIELD_UNKNOWN422(errors[] 里)不支持这个字段。
DSL_NOT_STRING422(errors[] 里)必须是字符串。
DSL_NOT_INTEGER422(errors[] 里)必须是整数。
DSL_NOT_BOOLEAN422(errors[] 里)必须是 true 或 false。
DSL_NOT_OBJECT422(errors[] 里)必须是键值对象。
DSL_NOT_LIST422(errors[] 里)必须是列表。
DSL_NOT_ONE_OF422(errors[] 里)取值只能是 {expected}。
DSL_TOO_SHORT422(errors[] 里)至少需要 {count} 个字符。
DSL_TOO_LONG422(errors[] 里)最多 {count} 个字符。
DSL_AT_LEAST422(errors[] 里)必须大于或等于 {limit}。
DSL_ABOVE422(errors[] 里)必须大于 {limit}。
DSL_AT_MOST422(errors[] 里)必须小于或等于 {limit}。
DSL_BELOW422(errors[] 里)必须小于 {limit}。
DSL_VALUE_INVALID422(errors[] 里)
DSL_RULE_ID_DUPLICATE422(errors[] 里)策略规则编号必须唯一。
DSL_V1_NO_APPROVAL422(errors[] 里)格式 v1 不支持需审批或降级规则。
DSL_DEGRADE_NEEDS_FALLBACK422(errors[] 里)降级规则必须指定 fallback_resource。
DSL_FALLBACK_ONLY_FOR_DEGRADE422(errors[] 里)只有降级规则可以指定 fallback_resource。
DSL_REGEX_INVALID422 / 409(errors[] 里)正则表达式无效。
DSL_REGEX_INVALID_AT422 / 409(errors[] 里)正则表达式在第 {position} 个字符处无效。
DSL_REGEX_TOO_LONG422 / 409(errors[] 里)正则表达式超过 {max} 个字符。
DSL_REGEX_TOTAL_TOO_LONG422 / 409(errors[] 里)策略里的正则表达式合计超过 {max} 个字符。
DSL_EXPIRES_INVALID422(errors[] 里)不是有效的 ISO 8601 时间;发布后会被视为已过期并拒绝全部动作。
DSL_EXPIRES_PAST422(errors[] 里)过期时间已过;发布后会拒绝全部动作。
DSL_REFUSED422(errors[] 里)

接入与资产 ​

代码状态说明
CONNECTION_OR_EXECUTOR_NOT_FOUND404接入或执行器不存在。
CONNECTION_REQUEST_REJECTED409接入地址、Agent 或资产登记无效、重复,或已达到限额。
CONNECTION_NOT_FOUND404接入不存在。
CONNECTION_NAME_INVALID422名称无效。
SDK_ADAPTER_UNAVAILABLE409SDK {version} 还没有 {framework} 适配器。
PUBLIC_ORIGIN_REQUIRED409请部署 HTTPS 控制面并配置 PREWORLD_GUARD_PUBLIC_ORIGIN。
CONNECTION_LIMIT409每个项目最多保留 100 个接入登记。
CONNECTION_AGENT_EXISTS409该 Agent 已登记,请轮换其接入包。
ASSET_LIMIT409项目资产登记上限为 2000 条。
ASSET_BATCH_SIZE409每批资产登记须为 1 至 200 条。
ASSET_NOT_CONNECTED409执行器只能登记已接入的资产。

SDK 下载令牌与私有源 ​

代码状态说明
SDK_DOWNLOAD_TOKEN_REQUIRED401SDK 下载需要有效的 SDK 下载令牌。
SDK_INDEX_NOT_CONFIGURED409控制面未配置私有 SDK 源。
SDK_TOKEN_NOT_FOUND404SDK 下载令牌不存在。
SDK_TOKEN_TTL_INVALID409SDK 下载令牌有效期须在 1 到 365 天之间。
SDK_TOKEN_LIMIT409每个项目最多保留 {max} 个有效的 SDK 下载令牌。

云托管 ​

代码状态说明
MANAGED_NOT_CONFIGURED503云托管尚未配置。
MANAGED_NOT_FOUND404托管资源不存在或访问已失效。
MANAGED_CONFLICT409状态、版本、配额或接入绑定不允许此操作。
MANAGED_CREDENTIAL_REQUIRED401需要有效凭据。
MANAGED_OPERATION_NOT_FOUND404操作不存在。
MANAGED_DOWNLOADS_NOT_CONFIGURED503下载服务尚未配置。