Stable vocabulary
Published reason codes are not repurposed. Minor releases can add new codes when new protocol behavior becomes observable.
Loading…
API documentation
Reason Codes
Reason codes are the stable explanation vocabulary attached to governed outcomes. They help humans, support workflows, and audit systems understand why Decionis allowed, blocked, escalated, or requested review.
Contract
Treat reason codes as explanation metadata. Applications should enforce the decision status or outcome, then display or store reason codes for audit context.
Audit friendly
Codes are uppercase, category-backed, and safe to persist in Decision Dossiers, support tickets, and downstream logs.
Not policy logic
A code can say policy matched or review is required. It does not expose the underlying policy rule or threshold.
Catalog route
Use the catalog route to populate admin UI labels, support runbooks, and typed SDK enums.
GET
/v1/protocol/reason-codesPublicReturn the current Decionis reason-code catalog with category, title, description, and stability fields.
curl https://api.decionis.com/v1/protocol/reason-codes{
"service": "decionis-protocol",
"protocol_version": "1.0.0",
"custom_reason_codes_supported": true,
"stability": "Stable codes will not be repurposed; new codes may be added in minor releases.",
"reason_codes": [
{
"code": "POLICY_MATCHED",
"category": "policy",
"title": "Policy matched",
"description": "A Decionis policy rule matched the submitted execution intent.",
"stability": "stable"
}
]
}Execution handling
Branch on the governed outcome. Use reason codes for display, audit, and escalation notes.
| Outcome | Application action | Reason-code role |
|---|---|---|
| APPROVE | Continue execution. | Explain why the gate allowed the action. |
| REJECT | Stop execution. | Explain why the gate blocked the action. |
| ESCALATE | Hand off to a reviewer. | Explain the escalation path and context. |
| REVIEW | Pause for review. | Explain missing evidence or review posture. |
Categories
Categories help teams group codes without inferring hidden policy logic.
| Category | Examples | Use |
|---|---|---|
| outcome | PROTOCOL_OUTCOME_APPROVE, PROTOCOL_OUTCOME_ESCALATE | Normalize the Decionis verdict across SDKs and native surfaces. |
| policy | POLICY_MATCHED, POLICY_GUARD_BLOCKED, MISSING_ORG_POLICY_BUNDLE | Explain policy resolution and provisioning posture. |
| risk | RISK_WITHIN_THRESHOLD, RISK_THRESHOLD_EXCEEDED | Summarize risk signal posture without exposing thresholds. |
| review | HUMAN_REVIEW_REQUIRED, MANUAL_VERIFICATION_REQUIRED | Drive reviewer handoff copy and queue routing. |
| override | OVERRIDE_APPROVED, OVERRIDE_REJECTED | Connect override outcomes to the original Decision Dossier. |
| system | PROTOCOL_ERROR | Route operational errors to support runbooks. |
SDK boundary
SDKs should expose reason codes, but they should not turn them into local policy engines.
Enforce the Decionis response
SDK callers should use evaluate or enforce, then store reason_codes alongside the Decision Dossier link. See /docs/decision-evaluation for the response shape and /docs/overrides for review and appeal trails.