Reason Codes
This page lists the reason and code values that OpenProdkt returns. Use it to read a deny, an allow, or an API error. For what to do next, see Troubleshooting.
For HTTP status codes, see the API Reference. This page lists codes only.
Decision reasons
These values appear in the reason field of a decision from the policy decision point (PDP).
| Reason | Decision | Meaning |
|---|---|---|
approval_required | approval_required | A policy requires approval before the call runs. |
asset_not_registered | allow | No registered asset matches the call. The call is not recorded as a decision or billed. The key is queued for discovery. In strict mode this is denied with default_deny_unregistered. |
no_policies_assigned | allow | The asset exists and has no published, active policies. In strict mode this is denied with default_deny_no_match. |
no_matching_policy | allow | Published, active policies are assigned, but none match the call. In strict mode this is denied with default_deny_no_match. |
default_deny_no_match | deny | strict mode only: no policy matched, or none is assigned. Recorded as a decision; billed only when policies were assigned. |
default_deny_unregistered | deny | strict mode only: no registered asset matches the call. Not recorded as a decision and not billed; the key is still queued for discovery. |
kill_switch_active | deny | An active kill switch covers the call. Checked before approvals, policies and the mode. Recorded as a decision and billed for a registered asset; not recorded or billed for an unregistered key. |
definition_changed | deny | strict mode only: the tool's definition differs from the pin you approved. Checked after the kill switch and before approvals and policies. Recorded as a decision and billed like any deny. |
policy_aggregate_matched | allow, approval_required, or deny | One or more policies matched. The most restrictive outcome wins and the winning policyId is returned. |
policy_evaluation_failed | Error (HTTP 503) | The PDP could not evaluate a policy. The call is not allowed and is recorded as a denied evaluation error. |
invalid_context | Error (HTTP 400); MCP deny tool result | Metadata, schema, numeric bounds, or runtime value kinds are invalid. No decision is recorded or charged, no approval is redeemed, and no upstream call occurs. |
approval_pending | approval_required | A retry arrived while the approval is still pending. |
approval_granted | allow | The approval was granted and has just been redeemed for this operation. |
approval_not_redeemable | deny | The approval exists but cannot be redeemed for this retry. |
asset_not_registered, no_policies_assigned, and no_matching_policy are allows, so the default for an unregistered or unassigned tool is to run it. See Security Model. In observe mode the response is unchanged and a would-deny event is recorded. In strict mode these calls are denied instead (default_deny_no_match and default_deny_unregistered), unless an active break-glass grant covers a registered asset, in which case the original allow reason is returned. An override can give an environment or asset type a different mode.
MCP wrapper reasons
These values appear in _meta.openprodkt.reason when the wrapper or the Envoy adapter does not run a tool. See MCP Adapter.
| Reason | Meaning |
|---|---|
approval_rejected | An approver rejected the operation. Do not retry. |
approval_revoked | An approver revoked the approval. Do not retry. |
approval_expired | The approval expired before it was used. Start a new approval. |
approval_grant_expired | The approval was granted, but the retry arrived after the grant window. Start a new approval. |
approval_consumed | The approval was already used for a run. Start a new approval for a new run. |
approval_not_found | No approval exists for this operation. |
asset_not_found | An explicit asset_id is unknown or not accessible to the caller. The tool is not called and no decision usage is consumed. |
execution_unknown | The tool started, but its result was not reported. Check the server's side effects before you retry. |
pdp_unavailable | The wrapper could not get a decision from the PDP. The call is denied. This includes an HTTP 503 with code enforcement_unavailable, returned when the kill switch state cannot be read. |
Operation status reasons
The operation status endpoint (status_url) returns a reason and a next_action.
| Reason | Meaning |
|---|---|
operation_in_progress | Another request for this operation is still being evaluated. |
execution_not_reported | The operation was allowed, but no outcome has been reported. |
execution_<status> | The reported outcome, for example execution_succeeded or execution_failed. |
next_action | Meaning |
|---|---|
wait, wait_for_approval | Poll again after the Retry-After interval. |
retry_same_operation | Retry with the same operation ID and request. |
request_new_approval | Start a new operation. |
stop | Do not retry. |
reconcile_upstream, read_upstream_result | Check the upstream system before acting again. |
Approval status
The approval_status field of an operation has these values. Read it from the operation's status_url.
| Status | Meaning |
|---|---|
pending | Waiting for an approver. |
approved | Approved. Retry within the grant window. |
rejected | Rejected. |
expired | Expired before approval. |
consumed | Approved and already used. |
API error codes
These values appear in the code field of an API error response.
| Code | Meaning |
|---|---|
unauthenticated | The credentials are missing or not valid. |
jwt_user_required | The action needs a signed-in user session. API keys are not accepted. |
self_approval_forbidden | The approver is the requester. Another user must approve. |
approvals_disabled | The approvals entitlement is not enabled for the organization. |
approval_not_found | No approval exists with this ID, or the caller cannot see it. |
approval_revoked | The approval was revoked. |
approval_retry_mismatch | The retry no longer matches the original request or published policy set. Preserve the request and operation ID for unchanged retries; a changed policy set requires a new approval flow. |
decision_quota_exceeded, approval_quota_exceeded, notification_quota_exceeded | HTTP 402. The monthly quota for that usage type is exhausted. See Limits and Configuration. |
policy_evaluation_failed | HTTP 503. A policy could not be evaluated. |
invalid_policy_condition | HTTP 400 on policy authoring, activation, rollback, publish, validate or simulate. Correct the namespace, operator, operand, or current-schema reference; the policy and revisions are unchanged. |
invalid_policy_state | HTTP 409. The lifecycle transition is unavailable: for example, publishing an already published policy, activating a draft or archived policy, or editing/restoring an archived policy. |
invalid_request | HTTP 400 on evaluation-facing and policy-preview routes. The JSON, request envelope, transport combination, outcome report, proposed-policy envelope or playground asset selection is invalid. Correct the request before retrying. |
invalid_context | HTTP 400. Correct metadata, schema violations, unsupported numbers, or incompatible runtime kinds before retrying. MCP stdio/Envoy MCP return an isError: true deny tool result with this reason. |
asset_not_found | HTTP 404. The asset_id is unknown or not accessible. |
invalid_operation_id | The operation ID is not valid. It must be 1 to 128 characters from letters, digits, ., _, :, and -. |
operation_id_conflict | The operation ID is already used for a different request. |
operation_in_progress | Another request with the same operation ID is still running. |
operation_not_found | No operation exists with this operation ID. |
operation_outcome_conflict | The outcome report conflicts with the outcome already recorded. |
invalid_vault_ref | HTTP 400. A vault_ref or vault_gap on an evaluation or outcome report is malformed, has the wrong kind, or both were sent. The message never repeats a value, and nothing is recorded. See Evidence Vault. |
vault_not_enabled | HTTP 422. The request carries a vault_ref but the evidence vault is off for the organization. Nothing is recorded. |
vault_unavailable | HTTP 503. The vault flag could not be read for a request that carries a vault_ref. Retry. |
invalid_enabled | HTTP 400 on PUT /v1/evidence-vault. The body must be exactly { "enabled": true } or { "enabled": false }. |
principal_not_found | HTTP 404 on the principal routes. The pseudonym is unknown, malformed, belongs to another organization, or (for the vault references) was erased. One fixed body for all of them. |
principal_active | HTTP 409 on erase. The member is still active; deactivate the member first. Nothing changed. |
invalid_pagination | HTTP 400 on the vault references: limit is 1 to 200 and offset is not negative. |
invalid_user_id | HTTP 400 on GET /v1/principals: user_id is required. |
operation_status_unavailable | The caller cannot read this operation's status. |
asset_identity_conflict | The tool identity is already bound to a different asset. Set asset_id to keep the identity. |
Every HTTP 400 from /v1/evaluate, /v1/proxy/evaluate,
/v1/proxy/outcomes, /v1/proxy/operations/{operation_id}, and
/v1/playground/decision includes both code and a human-readable error.
Use code, not message text, for programmatic handling. The codes on these
routes are invalid_request, invalid_context, and invalid_operation_id.
The operation-status endpoint retains invalid_operation_id for its path ID;
a missing operation ID in an evaluation request is invalid_request.
Request and context validation errors do not record or charge a decision,
consume approval, or change operation/outcome state. They do not authorize an
upstream call. SDKs preserve request/context outcomes. Generic Envoy preserves
the HTTP code; MCP stdio and Envoy MCP map invalid_context to a deny tool
result, while malformed requests remain JSON-RPC -32602. HTTP statuses and
which inputs are accepted are unchanged.
Policy authoring warnings
Warnings appear in a successful policy write's warnings string array, not as
decision reasons or errors.
| Warning | Meaning |
|---|---|
rule_field_optional | A deny or approval_required rule references a metadata leaf not explicitly required by the current schema. Saving remains allowed. Ordinary comparisons do not match absent fields; explicit presence/absence tests retain their defined behavior. |
See Policy authoring for schema and compatibility requirements.