Skip to content

API error codes ​

The error body ​

When the control plane refuses a request, the body is JSON:

json
{"detail": "Report at most 100 events at a time.", "code": "EVENT_BATCH_TOO_LARGE", "message": "Report at most 100 events at a time.", "params": {"max": 100}}
FieldMeaning
codeA stable code in UPPER_SNAKE case. Codes are added, never renamed. Act on this and the HTTP status
messageThe same sentence as detail, in the request's language
detailA string, except for request validation errors (REQUEST_INVALID), where it lists the problems; each item has type, loc and msg, never the submitted value
paramsOnly when the message has values in it. Scalars only, never secrets

Send X-Guard-Locale: en or X-Guard-Locale: zh to choose the language. /v1/ responses carry Content-Language. Without the header you get the older Chinese wording, kept unchanged for older clients.

The policy editor's validation error (POLICY_DSL_INVALID, 422) adds errors[], one item per problem with line, column, path, message, code and params. The DSL_* codes are those items' codes.

Responses that don't come from the control plane itself (a proxy's 502, a gateway timeout, a body that isn't JSON) have no code. Handle them by status.

The SDKs treat 401 and 403 as authentication errors and never fall back to the cached policy. They don't send a language header.

Decision reason codes ​

These are not HTTP errors. They are the reason_code of a decision, in events and in what the model sees.

Reason codeMeaning
ALLOWEDAllowed by policy
DEFAULT_DENYNot in the approved scope (deny by default)
RULE_DENIEDMatched a deny rule
APPROVAL_REQUIREDMatched an approval rule
APPROVEDApproved once
DEGRADEDMatched a degrade rule
POLICY_EXPIREDThe policy has expired
SUBJECT_REQUIREDNo trusted subject
POLICY_CHANGEDThe policy changed; start again
APPROVAL_NOT_CONSUMABLEThe approval ticket can no longer be used
GUARD_UNAVAILABLE and other GUARD_*Guard couldn't decide; the tool didn't run
FALLBACK_*The fallback tool isn't available or isn't allowed
MCP_*Refused at the MCP boundary
HTTP_*Refused at network egress

An HTTP_* reason code is not the same as an error response's code such as HTTP_404.

Error codes ​

Any endpoint ​

CodeStatusMessage
REQUEST_INVALID422These fields aren't valid: {fields}.
UNCLASSIFIED_CONFLICT409
HTTP_ERROR4xx / 5xxThe request didn't complete (HTTP {status}).
CROSS_SITE_REQUEST_REFUSED403Cross-site request refused.
RECORD_NOT_FOUND404Record not found, or not available to you.
SUBJECT_ID_REQUIRED409The trusted subject ID can't be empty.

Tokens, roles, sessions and SSO ​

CodeStatusMessage
RUNTIME_TOKEN_REQUIRED401A project token or executor credential is required.
RUNTIME_TOKEN_INVALID401The project token or executor credential is invalid, expired or revoked.
TOKEN_NOT_POLICY_ADMIN403This token can't manage policies.
TOKEN_NOT_OWNER403Only the project owner can manage project tokens.
EXECUTOR_TOKEN_CANNOT_READ403An executor credential can't read the project's audit or policy records.
TOKEN_NOT_EXECUTOR403This token can't report executor events.
MANAGED_GATEWAY_NEEDS_ENFORCE503The managed gateway needs a policy in Enforce mode.
TOKEN_NOT_REVIEWER403Only an independent reviewer's token can review policies.
NAMED_SIGN_IN_REQUIRED401Sign in with a named account.
SESSION_CSRF_INVALID403The session check failed. Sign in again.
ACCOUNT_CANNOT_REVIEW_ACTIONS403This account can't decide action approvals.
ACCOUNT_NOT_POLICY_ADMIN403This account can't manage policies.
ACCOUNT_OWNER_MANAGES403Only the project owner can manage named accounts.
ACCOUNT_OWNER_VIEWS403Only the project owner can view named accounts.
POLICY_REVIEW_NEEDS_REVIEWER403Only an independent reviewer can approve or reject a candidate policy.
SSO_NOT_CONFIGURED404SSO sign-in isn't configured.
SSO_UNAVAILABLE429SSO sign-in isn't available right now. Try again later.
SSO_INCOMPLETE401SSO sign-in didn't complete. Sign in again.
SSO_FAILED401SSO sign-in couldn't be verified. Sign in again.
SSO_SESSION_MISSING401No SSO session. Sign in again.
SSO_PROJECT_UNKNOWN— (answered as SSO_UNAVAILABLE)The identity provider's project isn't registered.
SSO_CAPACITY_FULL— (answered as SSO_UNAVAILABLE)Too many SSO sign-ins are in progress.
SSO_LOGIN_EXPIRED— (answered as SSO_FAILED)The SSO sign-in has expired.
SSO_ACCOUNT_DISABLED— (answered as SSO_FAILED)This SSO account is disabled.

Yi Labs sign-in, organizations and members ​

CodeStatusMessage
PREWORLD_NOT_CONFIGURED404 (page)Sign-in with a Yi Labs account isn't turned on for this Guard.
PREWORLD_LOGIN_EXPIRED400 (page)This sign-in has expired or was already used. Sign in again.
PREWORLD_ISSUER_MISMATCH400 (page)The sign-in answer didn't come from the Yi Labs account service this Guard is set up for, so it was refused. Sign in again.
PREWORLD_LOGIN_CANCELED401 (page)Sign-in was cancelled.
PREWORLD_LOGIN_FAILED401 (page)The Yi Labs sign-in couldn't be verified. Sign in again.
PREWORLD_UNAVAILABLE503 (page)The Yi Labs account service can't be reached right now. Try again later.
PREWORLD_RATE_LIMITED429 (page)Too many sign-ins were started from this network. Try again in a minute.
PREWORLD_ORG_NOT_LINKED403 (page)This organization has no available Guard workspace. Ask an owner to sign in first. Pre-provisioned spaces need their registered email; expired or disconnected spaces need support. You can also switch organizations or create your own.
PREWORLD_ORG_ALREADY_LINKED409 (page)This organization is already connected and can't be connected again.
PREWORLD_MEMBER_DISABLED403 / 403 (page)Your access to this Guard organization is disabled. Ask an owner.
PREWORLD_NO_PROJECT403 (page)This organization has no Guard project you can open.
PREWORLD_ORG_OWNER_REQUIRED403Only an owner of the current organization can create projects.
PREWORLD_PROJECT_REQUEST_CONFLICT409This creation request was already used with another name, or its project is closed. Refresh and try again.
PREWORLD_PROJECT_LIMIT409This organization has reached its 100-project creation limit. Contact support.
PREWORLD_PROJECT_UNKNOWN404This project isn't in the organization you signed in with.
PREWORLD_MEMBER_EXISTS409This email already belongs to a member of the project.
PREWORLD_MEMBER_ROLE_FROM_PREWORLD409This member owns the organization and is managed in the Yi Labs account: their role can't be changed, nor their access disabled, here.

Onboarding (self-hosted) ​

CodeStatusMessage
ONBOARDING_DISABLED403Onboarding is turned off.
ONBOARDING_NOT_CONFIGURED503No bootstrap token is configured.
ONBOARDING_KEY_INVALID403The bootstrap token is invalid.
ONBOARDING_NAMES_REQUIRED422Organization and project names can't be empty.

Executors, events and project tokens ​

CodeStatusMessage
AGENT_CREDENTIAL_MISMATCH403The agent doesn't match the executor credential.
EXECUTOR_NOT_FOUND404Executor not found.
EXECUTOR_V2_REQUIRED409The current policy uses format v2; the executor must support format v2.
POLICY_ACK_INCOMPLETE409A policy acknowledgement needs both the version and the hash.
POLICY_ACK_UNKNOWN409The policy version or hash the executor reported doesn't exist.
EXECUTOR_STATUS_INVALID409Invalid executor status.
TOKEN_ALREADY_INVALID409This token is no longer valid.
PROJECT_TOKEN_NOT_FOUND404Project token not found, or already revoked.
AUDIT_CURSOR_NOT_FOUND404The audit cursor doesn't exist or belongs to another project.
EVENT_BATCH_TOO_LARGE413Report at most {max} events at a time.
EVENT_AGENT_MISMATCH403The event's agent doesn't match the executor credential.
EVENT_PROJECT_MISMATCH403The event's project doesn't match this token.
EVENT_TENANT_MISMATCH403The event's tenant doesn't match this token.
EVENT_ID_TAKEN409This event ID belongs to another project.
EVENT_CAPACITY_FULL409The project's event storage is full. Archive events or raise the capacity.
EVENT_CURSOR_NOT_FOUND404The event cursor doesn't exist or belongs to another project.
TOKEN_ROLE_INVALID409Invalid project token role.
EVENT_FILTER_TIMEZONE409Time filters must include a time zone.
EVENT_FILTER_TIME_INVALID409The time filter {field} isn't a valid ISO 8601 time.
EVENT_FILTER_UNKNOWN409Unknown event filter.
SETTINGS_OUT_OF_RANGE409Retention or capacity is out of range.
ARCHIVE_PURGE_TOO_MANY409Purge at most 100 archived events at a time.
ARCHIVE_PURGE_REFUSED409The archive hash doesn't match, or the event is still within retention.

Member roles and trusted subjects ​

CodeStatusMessage
ACCOUNT_ROLE_INVALID409Invalid account role.
ACCOUNT_NOT_FOUND404Named account not found, or already disabled.
REVIEWER_SUBJECT_INVALID422A named account's trusted subject ID can't be empty or have leading or trailing spaces.
ACCOUNT_CANNOT_DISABLE_SELF409You can't disable the account you're signed in with.

Action approvals ​

CodeStatusMessage
APPROVAL_AGENT_MISMATCH403The approval's agent doesn't match the executor credential.
APPROVAL_PROJECT_MISMATCH403The approval's action doesn't match the executor's project.
TICKET_NOT_FOUND404Approval ticket not found.
APPROVAL_SUBJECT_REQUIRED422The action must carry a valid trusted subject ID.
APPROVAL_PREVIEW_FIELDS422An approval preview can only hold summary, destination and data_labels, never raw arguments.
APPROVAL_PREVIEW_TEXT_TOO_LONG422Approval preview text must be shorter than 200 characters.
APPROVAL_PREVIEW_LABELS_INVALID422Invalid data labels in the approval preview.
APPROVAL_PREVIEW_TOO_LARGE422The approval preview is too large.
APPROVAL_POLICY_CHANGED409The approval's policy changed or isn't in Enforce mode.
APPROVAL_RULE_NOT_FOUND409The current policy has no matching approval rule.
TICKET_DECISION_INVALID409Invalid approval decision.
TICKET_ALREADY_DECIDED409The approval ticket was already decided or has expired.
TICKET_SELF_APPROVAL409Whoever started an action can't approve it.
TICKET_POLICY_CHANGED409The policy behind this approval ticket has changed.
TICKET_DECIDED_ELSEWHERE409Someone else already decided this approval ticket.
TICKET_MISMATCH409The approval ticket doesn't match this action or executor.
TICKET_NOT_USABLE409The approval ticket isn't approved, has expired or was already used.
TICKET_USED_ELSEWHERE409Another executor already used this approval ticket.
TICKET_CANNOT_CANCEL409This approval ticket can't be cancelled.

Policies, reviews, publishing and rollback ​

CodeStatusMessage
CANDIDATE_NOT_FOUND404Candidate policy not found.
CANDIDATE_MODE_INVALID409Invalid candidate policy mode.
OBSERVATION_WINDOW_NOT_POSITIVE409The observation window and the minimum occurrences must be positive.
PREVIEW_BASIS_INVALID409Invalid replay basis: use attempted (all attempted actions) or completed (completed actions only).
OBSERVATION_WINDOW_INVALID422The observation window settings are out of range.
CANDIDATE_TTL_INVALID422A candidate policy must expire in 1 to 720 hours.
PREVIEW_RANGE_INVALID422The preview window or sample size is out of range.
CANDIDATE_NO_OBSERVED_ACTIONS409No successful action in the observation window reached the threshold, so there's nothing to allow.
REVIEW_COMMENT_TOO_LONG422A review comment can't be longer than 1000 characters.
POLICY_REVIEW_NOT_FOUND404Review not found.
POLICY_VERSION_CONFLICT409The policy has changed. Refresh, then publish again.
CANDIDATE_NOT_APPROVED409The candidate policy has to pass review first.
POLICY_REVIEW_MISMATCH409The review doesn't match the candidate policy, or isn't approved yet.
EVAL_FINDING_DIGEST_INVALID422The Eval finding bundle's digest doesn't match.
EVAL_FINDING_CONFLICT409A different finding with this finding_id already exists.
EVAL_FINDING_NOT_FOUND404Eval finding not found.
EVAL_FINDING_OTHER_PROJECT409This finding_id belongs to another project.
POLICY_DSL_INVALID422Invalid policy DSL:
POLICY_INVALID409 / 422Invalid policy:
POLICY_BODY_TOO_LARGE413The policy request is larger than {kib} KiB.
POLICY_VERSION_INVALID422A policy version must be a positive integer.
POLICY_VERSION_NOT_FOUND404Policy version not found.
ROLLBACK_AUDIT_MISSING500A rollback needs a control audit record.
ROLLBACK_TARGET_NOT_FOUND404The target policy version doesn't exist.
ROLLBACK_REASON_INVALID409The rollback reason must be 1 to 500 characters.
ROLLBACK_VERSION_CONFLICT409The policy has changed. Refresh, then roll back again.
ROLLBACK_TARGET_NOT_EARLIER409Roll back to an earlier policy version.
ROLLBACK_AUDIT_AMBIGUOUS409The rollback has no unique control audit record.
POLICY_V2_NEEDS_EXECUTORS409Before you publish a format v2 policy, every registered executor in the project must support format v2.
CANDIDATE_NOT_APPROVED_OR_EXPIRED409The candidate policy has to pass review and not be expired.
CANDIDATE_EXPIRED409The candidate policy has expired.
CANDIDATE_BASE_OUTDATED409The candidate was drafted on v{base}, but the policy is now v{current}. Draft it again from the current policy and submit it for review.
CANDIDATE_HASH_MISMATCH409The policy doesn't match the hash that was reviewed, so it wasn't published.
CANDIDATE_STATUS_TRANSITION409A candidate policy can't go from {current} to {target}.
POLICY_REVIEW_NEEDS_ACCOUNT409A review submitted from a named account must be bound to it.
CANDIDATE_CANNOT_REQUEST_REVIEW409This candidate policy can't be submitted for review.
POLICY_REVIEW_DECISION_INVALID409Invalid review decision.
POLICY_REVIEW_DECISION_NEEDS_ACCOUNT409A review decision from a named account must be bound to it.
POLICY_REVIEW_SAME_SUBJECT409Another trusted subject has to decide the review.
POLICY_REVIEW_ALREADY_DECIDED409The review is already decided.
CANDIDATE_NOT_IN_REVIEW409The candidate policy has expired or isn't in review.
POLICY_REVIEW_BY_AUTHOR409A policy's author can't review their own candidate; another trusted subject has to decide.

Policy editor diagnostics ​

CodeStatusMessage
DSL_YAML_ALIAS422 (in errors[])YAML aliases (*alias) aren't supported. Write the content out.
DSL_YAML_ANCHOR422 (in errors[])YAML anchors (&anchor) aren't supported. Write the content out.
DSL_YAML_TAG422 (in errors[])YAML tags such as {tag} aren't supported.
DSL_TOO_MANY_NODES422 (in errors[])The policy has more than {max} nodes.
DSL_TOO_DEEP422 (in errors[])The policy nests deeper than {max} levels.
DSL_MULTIPLE_DOCUMENTS422 (in errors[])Write a single YAML document.
DSL_KEY_NOT_STRING422 (in errors[])Object keys must be strings.
DSL_MERGE_KEY422 (in errors[])The YAML merge key << isn't supported.
DSL_DUPLICATE_KEY422 (in errors[])Duplicate key {key}.
DSL_SOURCE_TOO_LARGE422 (in errors[])The policy DSL is larger than {kib} KiB.
DSL_YAML_SYNTAX422 (in errors[])YAML syntax error:
DSL_YAML_UNPARSABLE422 (in errors[])The YAML can't be parsed:
DSL_DOCUMENT_TOO_LARGE422 (in errors[])The policy document is larger than {kib} KiB.
DSL_DOCUMENT_TOO_COMPLEX422 (in errors[])The policy document nests too deeply or has too many nodes.
DSL_SOURCE_OR_DOCUMENT422 (in errors[])Send exactly one of source (YAML text) or document (a JSON object).
DSL_NOT_A_MAPPING422 (in errors[])The policy document must be a YAML mapping.
DSL_INVALID422 (in errors[])The policy document isn't valid.
DSL_FIELD_MISSING422 (in errors[])This field is required.
DSL_FIELD_UNKNOWN422 (in errors[])This field isn't supported.
DSL_NOT_STRING422 (in errors[])Must be a string.
DSL_NOT_INTEGER422 (in errors[])Must be an integer.
DSL_NOT_BOOLEAN422 (in errors[])Must be true or false.
DSL_NOT_OBJECT422 (in errors[])Must be an object.
DSL_NOT_LIST422 (in errors[])Must be a list.
DSL_NOT_ONE_OF422 (in errors[])Must be one of {expected}.
DSL_TOO_SHORT422 (in errors[])Needs at least {count} characters.
DSL_TOO_LONG422 (in errors[])At most {count} characters.
DSL_AT_LEAST422 (in errors[])Must be at least {limit}.
DSL_ABOVE422 (in errors[])Must be greater than {limit}.
DSL_AT_MOST422 (in errors[])Must be at most {limit}.
DSL_BELOW422 (in errors[])Must be less than {limit}.
DSL_VALUE_INVALID422 (in errors[])
DSL_RULE_ID_DUPLICATE422 (in errors[])Rule IDs must be unique.
DSL_V1_NO_APPROVAL422 (in errors[])Format v1 doesn't support approval or degrade rules.
DSL_DEGRADE_NEEDS_FALLBACK422 (in errors[])A degrade rule must set fallback_resource.
DSL_FALLBACK_ONLY_FOR_DEGRADE422 (in errors[])Only a degrade rule can set fallback_resource.
DSL_REGEX_INVALID422 / 409 (in errors[])Invalid regular expression.
DSL_REGEX_INVALID_AT422 / 409 (in errors[])The regular expression is invalid at character {position}.
DSL_REGEX_TOO_LONG422 / 409 (in errors[])The regular expression is longer than {max} characters.
DSL_REGEX_TOTAL_TOO_LONG422 / 409 (in errors[])The policy's regular expressions add up to more than {max} characters.
DSL_EXPIRES_INVALID422 (in errors[])Not a valid ISO 8601 time; once published, the policy would count as expired and deny every action.
DSL_EXPIRES_PAST422 (in errors[])This time has passed; once published, the policy would deny every action.
DSL_REFUSED422 (in errors[])

Connections and assets ​

CodeStatusMessage
CONNECTION_OR_EXECUTOR_NOT_FOUND404Connection or executor not found.
CONNECTION_REQUEST_REJECTED409The connection address, agent or asset registration is invalid, duplicated or over the limit.
CONNECTION_NOT_FOUND404Connection not found.
CONNECTION_NAME_INVALID422Invalid name.
SDK_ADAPTER_UNAVAILABLE409SDK {version} has no {framework} adapter yet.
PUBLIC_ORIGIN_REQUIRED409Serve the control plane over HTTPS and set PREWORLD_GUARD_PUBLIC_ORIGIN.
CONNECTION_LIMIT409A project can keep at most 100 connections.
CONNECTION_AGENT_EXISTS409This agent is already connected. Rotate its connection package instead.
ASSET_LIMIT409A project can register at most 2000 assets.
ASSET_BATCH_SIZE409Register 1 to 200 assets at a time.
ASSET_NOT_CONNECTED409An executor can only register assets it's connected for.

SDK download tokens and the private index ​

CodeStatusMessage
SDK_DOWNLOAD_TOKEN_REQUIRED401SDK downloads need a valid SDK download token.
SDK_INDEX_NOT_CONFIGURED409The control plane has no private SDK index.
SDK_TOKEN_NOT_FOUND404SDK download token not found.
SDK_TOKEN_TTL_INVALID409An SDK download token must expire in 1 to 365 days.
SDK_TOKEN_LIMIT409A project can keep at most {max} active SDK download tokens.

Managed cloud ​

CodeStatusMessage
MANAGED_NOT_CONFIGURED503The managed cloud isn't configured.
MANAGED_NOT_FOUND404Managed resource not found, or access has expired.
MANAGED_CONFLICT409The state, version, quota or binding doesn't allow this.
MANAGED_CREDENTIAL_REQUIRED401A valid credential is required.
MANAGED_OPERATION_NOT_FOUND404Operation not found.
MANAGED_DOWNLOADS_NOT_CONFIGURED503The download service isn't configured.