API error codes
The error body
When the control plane refuses a request, the body is 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}}| Field | Meaning |
|---|---|
code | A stable code in UPPER_SNAKE case. Codes are added, never renamed. Act on this and the HTTP status |
message | The same sentence as detail, in the request's language |
detail | A string, except for request validation errors (REQUEST_INVALID), where it lists the problems; each item has type, loc and msg, never the submitted value |
params | Only 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 code | Meaning |
|---|---|
ALLOWED | Allowed by policy |
DEFAULT_DENY | Not in the approved scope (deny by default) |
RULE_DENIED | Matched a deny rule |
APPROVAL_REQUIRED | Matched an approval rule |
APPROVED | Approved once |
DEGRADED | Matched a degrade rule |
POLICY_EXPIRED | The policy has expired |
SUBJECT_REQUIRED | No trusted subject |
POLICY_CHANGED | The policy changed; start again |
APPROVAL_NOT_CONSUMABLE | The 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
| Code | Status | Message |
|---|---|---|
REQUEST_INVALID | 422 | These fields aren't valid: {fields}. |
UNCLASSIFIED_CONFLICT | 409 | |
HTTP_ERROR | 4xx / 5xx | The request didn't complete (HTTP {status}). |
CROSS_SITE_REQUEST_REFUSED | 403 | Cross-site request refused. |
RECORD_NOT_FOUND | 404 | Record not found, or not available to you. |
SUBJECT_ID_REQUIRED | 409 | The trusted subject ID can't be empty. |
Tokens, roles, sessions and SSO
| Code | Status | Message |
|---|---|---|
RUNTIME_TOKEN_REQUIRED | 401 | A project token or executor credential is required. |
RUNTIME_TOKEN_INVALID | 401 | The project token or executor credential is invalid, expired or revoked. |
TOKEN_NOT_POLICY_ADMIN | 403 | This token can't manage policies. |
TOKEN_NOT_OWNER | 403 | Only the project owner can manage project tokens. |
EXECUTOR_TOKEN_CANNOT_READ | 403 | An executor credential can't read the project's audit or policy records. |
TOKEN_NOT_EXECUTOR | 403 | This token can't report executor events. |
MANAGED_GATEWAY_NEEDS_ENFORCE | 503 | The managed gateway needs a policy in Enforce mode. |
TOKEN_NOT_REVIEWER | 403 | Only an independent reviewer's token can review policies. |
NAMED_SIGN_IN_REQUIRED | 401 | Sign in with a named account. |
SESSION_CSRF_INVALID | 403 | The session check failed. Sign in again. |
ACCOUNT_CANNOT_REVIEW_ACTIONS | 403 | This account can't decide action approvals. |
ACCOUNT_NOT_POLICY_ADMIN | 403 | This account can't manage policies. |
ACCOUNT_OWNER_MANAGES | 403 | Only the project owner can manage named accounts. |
ACCOUNT_OWNER_VIEWS | 403 | Only the project owner can view named accounts. |
POLICY_REVIEW_NEEDS_REVIEWER | 403 | Only an independent reviewer can approve or reject a candidate policy. |
SSO_NOT_CONFIGURED | 404 | SSO sign-in isn't configured. |
SSO_UNAVAILABLE | 429 | SSO sign-in isn't available right now. Try again later. |
SSO_INCOMPLETE | 401 | SSO sign-in didn't complete. Sign in again. |
SSO_FAILED | 401 | SSO sign-in couldn't be verified. Sign in again. |
SSO_SESSION_MISSING | 401 | No 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
| Code | Status | Message |
|---|---|---|
PREWORLD_NOT_CONFIGURED | 404 (page) | Sign-in with a Yi Labs account isn't turned on for this Guard. |
PREWORLD_LOGIN_EXPIRED | 400 (page) | This sign-in has expired or was already used. Sign in again. |
PREWORLD_ISSUER_MISMATCH | 400 (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_CANCELED | 401 (page) | Sign-in was cancelled. |
PREWORLD_LOGIN_FAILED | 401 (page) | The Yi Labs sign-in couldn't be verified. Sign in again. |
PREWORLD_UNAVAILABLE | 503 (page) | The Yi Labs account service can't be reached right now. Try again later. |
PREWORLD_RATE_LIMITED | 429 (page) | Too many sign-ins were started from this network. Try again in a minute. |
PREWORLD_ORG_NOT_LINKED | 403 (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_LINKED | 409 (page) | This organization is already connected and can't be connected again. |
PREWORLD_MEMBER_DISABLED | 403 / 403 (page) | Your access to this Guard organization is disabled. Ask an owner. |
PREWORLD_NO_PROJECT | 403 (page) | This organization has no Guard project you can open. |
PREWORLD_ORG_OWNER_REQUIRED | 403 | Only an owner of the current organization can create projects. |
PREWORLD_PROJECT_REQUEST_CONFLICT | 409 | This creation request was already used with another name, or its project is closed. Refresh and try again. |
PREWORLD_PROJECT_LIMIT | 409 | This organization has reached its 100-project creation limit. Contact support. |
PREWORLD_PROJECT_UNKNOWN | 404 | This project isn't in the organization you signed in with. |
PREWORLD_MEMBER_EXISTS | 409 | This email already belongs to a member of the project. |
PREWORLD_MEMBER_ROLE_FROM_PREWORLD | 409 | This 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)
| Code | Status | Message |
|---|---|---|
ONBOARDING_DISABLED | 403 | Onboarding is turned off. |
ONBOARDING_NOT_CONFIGURED | 503 | No bootstrap token is configured. |
ONBOARDING_KEY_INVALID | 403 | The bootstrap token is invalid. |
ONBOARDING_NAMES_REQUIRED | 422 | Organization and project names can't be empty. |
Executors, events and project tokens
| Code | Status | Message |
|---|---|---|
AGENT_CREDENTIAL_MISMATCH | 403 | The agent doesn't match the executor credential. |
EXECUTOR_NOT_FOUND | 404 | Executor not found. |
EXECUTOR_V2_REQUIRED | 409 | The current policy uses format v2; the executor must support format v2. |
POLICY_ACK_INCOMPLETE | 409 | A policy acknowledgement needs both the version and the hash. |
POLICY_ACK_UNKNOWN | 409 | The policy version or hash the executor reported doesn't exist. |
EXECUTOR_STATUS_INVALID | 409 | Invalid executor status. |
TOKEN_ALREADY_INVALID | 409 | This token is no longer valid. |
PROJECT_TOKEN_NOT_FOUND | 404 | Project token not found, or already revoked. |
AUDIT_CURSOR_NOT_FOUND | 404 | The audit cursor doesn't exist or belongs to another project. |
EVENT_BATCH_TOO_LARGE | 413 | Report at most {max} events at a time. |
EVENT_AGENT_MISMATCH | 403 | The event's agent doesn't match the executor credential. |
EVENT_PROJECT_MISMATCH | 403 | The event's project doesn't match this token. |
EVENT_TENANT_MISMATCH | 403 | The event's tenant doesn't match this token. |
EVENT_ID_TAKEN | 409 | This event ID belongs to another project. |
EVENT_CAPACITY_FULL | 409 | The project's event storage is full. Archive events or raise the capacity. |
EVENT_CURSOR_NOT_FOUND | 404 | The event cursor doesn't exist or belongs to another project. |
TOKEN_ROLE_INVALID | 409 | Invalid project token role. |
EVENT_FILTER_TIMEZONE | 409 | Time filters must include a time zone. |
EVENT_FILTER_TIME_INVALID | 409 | The time filter {field} isn't a valid ISO 8601 time. |
EVENT_FILTER_UNKNOWN | 409 | Unknown event filter. |
SETTINGS_OUT_OF_RANGE | 409 | Retention or capacity is out of range. |
ARCHIVE_PURGE_TOO_MANY | 409 | Purge at most 100 archived events at a time. |
ARCHIVE_PURGE_REFUSED | 409 | The archive hash doesn't match, or the event is still within retention. |
Member roles and trusted subjects
| Code | Status | Message |
|---|---|---|
ACCOUNT_ROLE_INVALID | 409 | Invalid account role. |
ACCOUNT_NOT_FOUND | 404 | Named account not found, or already disabled. |
REVIEWER_SUBJECT_INVALID | 422 | A named account's trusted subject ID can't be empty or have leading or trailing spaces. |
ACCOUNT_CANNOT_DISABLE_SELF | 409 | You can't disable the account you're signed in with. |
Action approvals
| Code | Status | Message |
|---|---|---|
APPROVAL_AGENT_MISMATCH | 403 | The approval's agent doesn't match the executor credential. |
APPROVAL_PROJECT_MISMATCH | 403 | The approval's action doesn't match the executor's project. |
TICKET_NOT_FOUND | 404 | Approval ticket not found. |
APPROVAL_SUBJECT_REQUIRED | 422 | The action must carry a valid trusted subject ID. |
APPROVAL_PREVIEW_FIELDS | 422 | An approval preview can only hold summary, destination and data_labels, never raw arguments. |
APPROVAL_PREVIEW_TEXT_TOO_LONG | 422 | Approval preview text must be shorter than 200 characters. |
APPROVAL_PREVIEW_LABELS_INVALID | 422 | Invalid data labels in the approval preview. |
APPROVAL_PREVIEW_TOO_LARGE | 422 | The approval preview is too large. |
APPROVAL_POLICY_CHANGED | 409 | The approval's policy changed or isn't in Enforce mode. |
APPROVAL_RULE_NOT_FOUND | 409 | The current policy has no matching approval rule. |
TICKET_DECISION_INVALID | 409 | Invalid approval decision. |
TICKET_ALREADY_DECIDED | 409 | The approval ticket was already decided or has expired. |
TICKET_SELF_APPROVAL | 409 | Whoever started an action can't approve it. |
TICKET_POLICY_CHANGED | 409 | The policy behind this approval ticket has changed. |
TICKET_DECIDED_ELSEWHERE | 409 | Someone else already decided this approval ticket. |
TICKET_MISMATCH | 409 | The approval ticket doesn't match this action or executor. |
TICKET_NOT_USABLE | 409 | The approval ticket isn't approved, has expired or was already used. |
TICKET_USED_ELSEWHERE | 409 | Another executor already used this approval ticket. |
TICKET_CANNOT_CANCEL | 409 | This approval ticket can't be cancelled. |
Policies, reviews, publishing and rollback
| Code | Status | Message |
|---|---|---|
CANDIDATE_NOT_FOUND | 404 | Candidate policy not found. |
CANDIDATE_MODE_INVALID | 409 | Invalid candidate policy mode. |
OBSERVATION_WINDOW_NOT_POSITIVE | 409 | The observation window and the minimum occurrences must be positive. |
PREVIEW_BASIS_INVALID | 409 | Invalid replay basis: use attempted (all attempted actions) or completed (completed actions only). |
OBSERVATION_WINDOW_INVALID | 422 | The observation window settings are out of range. |
CANDIDATE_TTL_INVALID | 422 | A candidate policy must expire in 1 to 720 hours. |
PREVIEW_RANGE_INVALID | 422 | The preview window or sample size is out of range. |
CANDIDATE_NO_OBSERVED_ACTIONS | 409 | No successful action in the observation window reached the threshold, so there's nothing to allow. |
REVIEW_COMMENT_TOO_LONG | 422 | A review comment can't be longer than 1000 characters. |
POLICY_REVIEW_NOT_FOUND | 404 | Review not found. |
POLICY_VERSION_CONFLICT | 409 | The policy has changed. Refresh, then publish again. |
CANDIDATE_NOT_APPROVED | 409 | The candidate policy has to pass review first. |
POLICY_REVIEW_MISMATCH | 409 | The review doesn't match the candidate policy, or isn't approved yet. |
EVAL_FINDING_DIGEST_INVALID | 422 | The Eval finding bundle's digest doesn't match. |
EVAL_FINDING_CONFLICT | 409 | A different finding with this finding_id already exists. |
EVAL_FINDING_NOT_FOUND | 404 | Eval finding not found. |
EVAL_FINDING_OTHER_PROJECT | 409 | This finding_id belongs to another project. |
POLICY_DSL_INVALID | 422 | Invalid policy DSL: |
POLICY_INVALID | 409 / 422 | Invalid policy: |
POLICY_BODY_TOO_LARGE | 413 | The policy request is larger than {kib} KiB. |
POLICY_VERSION_INVALID | 422 | A policy version must be a positive integer. |
POLICY_VERSION_NOT_FOUND | 404 | Policy version not found. |
ROLLBACK_AUDIT_MISSING | 500 | A rollback needs a control audit record. |
ROLLBACK_TARGET_NOT_FOUND | 404 | The target policy version doesn't exist. |
ROLLBACK_REASON_INVALID | 409 | The rollback reason must be 1 to 500 characters. |
ROLLBACK_VERSION_CONFLICT | 409 | The policy has changed. Refresh, then roll back again. |
ROLLBACK_TARGET_NOT_EARLIER | 409 | Roll back to an earlier policy version. |
ROLLBACK_AUDIT_AMBIGUOUS | 409 | The rollback has no unique control audit record. |
POLICY_V2_NEEDS_EXECUTORS | 409 | Before you publish a format v2 policy, every registered executor in the project must support format v2. |
CANDIDATE_NOT_APPROVED_OR_EXPIRED | 409 | The candidate policy has to pass review and not be expired. |
CANDIDATE_EXPIRED | 409 | The candidate policy has expired. |
CANDIDATE_BASE_OUTDATED | 409 | The 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_MISMATCH | 409 | The policy doesn't match the hash that was reviewed, so it wasn't published. |
CANDIDATE_STATUS_TRANSITION | 409 | A candidate policy can't go from {current} to {target}. |
POLICY_REVIEW_NEEDS_ACCOUNT | 409 | A review submitted from a named account must be bound to it. |
CANDIDATE_CANNOT_REQUEST_REVIEW | 409 | This candidate policy can't be submitted for review. |
POLICY_REVIEW_DECISION_INVALID | 409 | Invalid review decision. |
POLICY_REVIEW_DECISION_NEEDS_ACCOUNT | 409 | A review decision from a named account must be bound to it. |
POLICY_REVIEW_SAME_SUBJECT | 409 | Another trusted subject has to decide the review. |
POLICY_REVIEW_ALREADY_DECIDED | 409 | The review is already decided. |
CANDIDATE_NOT_IN_REVIEW | 409 | The candidate policy has expired or isn't in review. |
POLICY_REVIEW_BY_AUTHOR | 409 | A policy's author can't review their own candidate; another trusted subject has to decide. |
Policy editor diagnostics
| Code | Status | Message |
|---|---|---|
DSL_YAML_ALIAS | 422 (in errors[]) | YAML aliases (*alias) aren't supported. Write the content out. |
DSL_YAML_ANCHOR | 422 (in errors[]) | YAML anchors (&anchor) aren't supported. Write the content out. |
DSL_YAML_TAG | 422 (in errors[]) | YAML tags such as {tag} aren't supported. |
DSL_TOO_MANY_NODES | 422 (in errors[]) | The policy has more than {max} nodes. |
DSL_TOO_DEEP | 422 (in errors[]) | The policy nests deeper than {max} levels. |
DSL_MULTIPLE_DOCUMENTS | 422 (in errors[]) | Write a single YAML document. |
DSL_KEY_NOT_STRING | 422 (in errors[]) | Object keys must be strings. |
DSL_MERGE_KEY | 422 (in errors[]) | The YAML merge key << isn't supported. |
DSL_DUPLICATE_KEY | 422 (in errors[]) | Duplicate key {key}. |
DSL_SOURCE_TOO_LARGE | 422 (in errors[]) | The policy DSL is larger than {kib} KiB. |
DSL_YAML_SYNTAX | 422 (in errors[]) | YAML syntax error: |
DSL_YAML_UNPARSABLE | 422 (in errors[]) | The YAML can't be parsed: |
DSL_DOCUMENT_TOO_LARGE | 422 (in errors[]) | The policy document is larger than {kib} KiB. |
DSL_DOCUMENT_TOO_COMPLEX | 422 (in errors[]) | The policy document nests too deeply or has too many nodes. |
DSL_SOURCE_OR_DOCUMENT | 422 (in errors[]) | Send exactly one of source (YAML text) or document (a JSON object). |
DSL_NOT_A_MAPPING | 422 (in errors[]) | The policy document must be a YAML mapping. |
DSL_INVALID | 422 (in errors[]) | The policy document isn't valid. |
DSL_FIELD_MISSING | 422 (in errors[]) | This field is required. |
DSL_FIELD_UNKNOWN | 422 (in errors[]) | This field isn't supported. |
DSL_NOT_STRING | 422 (in errors[]) | Must be a string. |
DSL_NOT_INTEGER | 422 (in errors[]) | Must be an integer. |
DSL_NOT_BOOLEAN | 422 (in errors[]) | Must be true or false. |
DSL_NOT_OBJECT | 422 (in errors[]) | Must be an object. |
DSL_NOT_LIST | 422 (in errors[]) | Must be a list. |
DSL_NOT_ONE_OF | 422 (in errors[]) | Must be one of {expected}. |
DSL_TOO_SHORT | 422 (in errors[]) | Needs at least {count} characters. |
DSL_TOO_LONG | 422 (in errors[]) | At most {count} characters. |
DSL_AT_LEAST | 422 (in errors[]) | Must be at least {limit}. |
DSL_ABOVE | 422 (in errors[]) | Must be greater than {limit}. |
DSL_AT_MOST | 422 (in errors[]) | Must be at most {limit}. |
DSL_BELOW | 422 (in errors[]) | Must be less than {limit}. |
DSL_VALUE_INVALID | 422 (in errors[]) | |
DSL_RULE_ID_DUPLICATE | 422 (in errors[]) | Rule IDs must be unique. |
DSL_V1_NO_APPROVAL | 422 (in errors[]) | Format v1 doesn't support approval or degrade rules. |
DSL_DEGRADE_NEEDS_FALLBACK | 422 (in errors[]) | A degrade rule must set fallback_resource. |
DSL_FALLBACK_ONLY_FOR_DEGRADE | 422 (in errors[]) | Only a degrade rule can set fallback_resource. |
DSL_REGEX_INVALID | 422 / 409 (in errors[]) | Invalid regular expression. |
DSL_REGEX_INVALID_AT | 422 / 409 (in errors[]) | The regular expression is invalid at character {position}. |
DSL_REGEX_TOO_LONG | 422 / 409 (in errors[]) | The regular expression is longer than {max} characters. |
DSL_REGEX_TOTAL_TOO_LONG | 422 / 409 (in errors[]) | The policy's regular expressions add up to more than {max} characters. |
DSL_EXPIRES_INVALID | 422 (in errors[]) | Not a valid ISO 8601 time; once published, the policy would count as expired and deny every action. |
DSL_EXPIRES_PAST | 422 (in errors[]) | This time has passed; once published, the policy would deny every action. |
DSL_REFUSED | 422 (in errors[]) |
Connections and assets
| Code | Status | Message |
|---|---|---|
CONNECTION_OR_EXECUTOR_NOT_FOUND | 404 | Connection or executor not found. |
CONNECTION_REQUEST_REJECTED | 409 | The connection address, agent or asset registration is invalid, duplicated or over the limit. |
CONNECTION_NOT_FOUND | 404 | Connection not found. |
CONNECTION_NAME_INVALID | 422 | Invalid name. |
SDK_ADAPTER_UNAVAILABLE | 409 | SDK {version} has no {framework} adapter yet. |
PUBLIC_ORIGIN_REQUIRED | 409 | Serve the control plane over HTTPS and set PREWORLD_GUARD_PUBLIC_ORIGIN. |
CONNECTION_LIMIT | 409 | A project can keep at most 100 connections. |
CONNECTION_AGENT_EXISTS | 409 | This agent is already connected. Rotate its connection package instead. |
ASSET_LIMIT | 409 | A project can register at most 2000 assets. |
ASSET_BATCH_SIZE | 409 | Register 1 to 200 assets at a time. |
ASSET_NOT_CONNECTED | 409 | An executor can only register assets it's connected for. |
SDK download tokens and the private index
| Code | Status | Message |
|---|---|---|
SDK_DOWNLOAD_TOKEN_REQUIRED | 401 | SDK downloads need a valid SDK download token. |
SDK_INDEX_NOT_CONFIGURED | 409 | The control plane has no private SDK index. |
SDK_TOKEN_NOT_FOUND | 404 | SDK download token not found. |
SDK_TOKEN_TTL_INVALID | 409 | An SDK download token must expire in 1 to 365 days. |
SDK_TOKEN_LIMIT | 409 | A project can keep at most {max} active SDK download tokens. |
Managed cloud
| Code | Status | Message |
|---|---|---|
MANAGED_NOT_CONFIGURED | 503 | The managed cloud isn't configured. |
MANAGED_NOT_FOUND | 404 | Managed resource not found, or access has expired. |
MANAGED_CONFLICT | 409 | The state, version, quota or binding doesn't allow this. |
MANAGED_CREDENTIAL_REQUIRED | 401 | A valid credential is required. |
MANAGED_OPERATION_NOT_FOUND | 404 | Operation not found. |
MANAGED_DOWNLOADS_NOT_CONFIGURED | 503 | The download service isn't configured. |