Skip to main content

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).

ReasonDecisionMeaning
approval_requiredapproval_requiredA policy requires approval before the call runs.
asset_not_registeredallowNo 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_assignedallowThe asset exists and has no published, active policies. In strict mode this is denied with default_deny_no_match.
no_matching_policyallowPublished, active policies are assigned, but none match the call. In strict mode this is denied with default_deny_no_match.
default_deny_no_matchdenystrict mode only: no policy matched, or none is assigned. Recorded as a decision; billed only when policies were assigned.
default_deny_unregistereddenystrict 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_activedenyAn 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_changeddenystrict 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_matchedallow, approval_required, or denyOne or more policies matched. The most restrictive outcome wins and the winning policyId is returned.
policy_evaluation_failedError (HTTP 503)The PDP could not evaluate a policy. The call is not allowed and is recorded as a denied evaluation error.
invalid_contextError (HTTP 400); MCP deny tool resultMetadata, 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_pendingapproval_requiredA retry arrived while the approval is still pending.
approval_grantedallowThe approval was granted and has just been redeemed for this operation.
approval_not_redeemabledenyThe 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.

ReasonMeaning
approval_rejectedAn approver rejected the operation. Do not retry.
approval_revokedAn approver revoked the approval. Do not retry.
approval_expiredThe approval expired before it was used. Start a new approval.
approval_grant_expiredThe approval was granted, but the retry arrived after the grant window. Start a new approval.
approval_consumedThe approval was already used for a run. Start a new approval for a new run.
approval_not_foundNo approval exists for this operation.
asset_not_foundAn explicit asset_id is unknown or not accessible to the caller. The tool is not called and no decision usage is consumed.
execution_unknownThe tool started, but its result was not reported. Check the server's side effects before you retry.
pdp_unavailableThe 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.

ReasonMeaning
operation_in_progressAnother request for this operation is still being evaluated.
execution_not_reportedThe operation was allowed, but no outcome has been reported.
execution_<status>The reported outcome, for example execution_succeeded or execution_failed.
next_actionMeaning
wait, wait_for_approvalPoll again after the Retry-After interval.
retry_same_operationRetry with the same operation ID and request.
request_new_approvalStart a new operation.
stopDo not retry.
reconcile_upstream, read_upstream_resultCheck 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.

StatusMeaning
pendingWaiting for an approver.
approvedApproved. Retry within the grant window.
rejectedRejected.
expiredExpired before approval.
consumedApproved and already used.

API error codes​

These values appear in the code field of an API error response.

CodeMeaning
unauthenticatedThe credentials are missing or not valid.
jwt_user_requiredThe action needs a signed-in user session. API keys are not accepted.
self_approval_forbiddenThe approver is the requester. Another user must approve.
approvals_disabledThe approvals entitlement is not enabled for the organization.
approval_not_foundNo approval exists with this ID, or the caller cannot see it.
approval_revokedThe approval was revoked.
approval_retry_mismatchThe 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_exceededHTTP 402. The monthly quota for that usage type is exhausted. See Limits and Configuration.
policy_evaluation_failedHTTP 503. A policy could not be evaluated.
invalid_policy_conditionHTTP 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_stateHTTP 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_requestHTTP 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_contextHTTP 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_foundHTTP 404. The asset_id is unknown or not accessible.
invalid_operation_idThe operation ID is not valid. It must be 1 to 128 characters from letters, digits, ., _, :, and -.
operation_id_conflictThe operation ID is already used for a different request.
operation_in_progressAnother request with the same operation ID is still running.
operation_not_foundNo operation exists with this operation ID.
operation_outcome_conflictThe outcome report conflicts with the outcome already recorded.
invalid_vault_refHTTP 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_enabledHTTP 422. The request carries a vault_ref but the evidence vault is off for the organization. Nothing is recorded.
vault_unavailableHTTP 503. The vault flag could not be read for a request that carries a vault_ref. Retry.
invalid_enabledHTTP 400 on PUT /v1/evidence-vault. The body must be exactly { "enabled": true } or { "enabled": false }.
principal_not_foundHTTP 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_activeHTTP 409 on erase. The member is still active; deactivate the member first. Nothing changed.
invalid_paginationHTTP 400 on the vault references: limit is 1 to 200 and offset is not negative.
invalid_user_idHTTP 400 on GET /v1/principals: user_id is required.
operation_status_unavailableThe caller cannot read this operation's status.
asset_identity_conflictThe 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.

WarningMeaning
rule_field_optionalA 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.