Error codes

Errors follow a consistent shape across API and CLI:

{"error": {"code": "OrkenaError.POLICY_DENIED", "message": "...", "seq": 417}}

Policy and authorization#

Code	Meaning	Fix
OrkenaError.POLICY_DENIED	An action was denied by policy	Review the verdict reason and the policy pack
OrkenaError.POLICY_NO_MATCH	No rule matched the action	Add an explicit permit or forbid rule
OrkenaError.GATE_BLOCKED_SELF_APPROVAL	The initiator tried to approve their own request	Use a different approver
OrkenaError.GATE_SAME_TEAM	Approver blocked by the same-team rule	Route to a different team
OrkenaError.GATE_QUORUM_NOT_MET	The gate is still waiting for approvals	Wait, or escalate
OrkenaError.CREDENTIAL_SCOPE	Credential use outside its scope	Fix the credential scope binding

Runtime and runs#

Code	Meaning	Fix
OrkenaError.RUN_NOT_FOUND	Unknown run id	Check the id
OrkenaError.RUN_TERMINAL	Operation on a finished run	Replay or fork instead
OrkenaError.CHECKPOINT_NOT_FOUND	Fork requested from an unknown checkpoint	Use a listed checkpoint
OrkenaError.TOOL_FAILED	A tool call failed	Check the tool logs
OrkenaError.TOOL_TAINTED	A tool call was denied due to tainted input	Route through a gate or sanitize

Graph and versioning#

Code	Meaning	Fix
OrkenaError.GRAPH_INVALID	The graph definition is invalid	Validate with orkena graph validate
OrkenaError.VERSION_IMMUTABLE	Attempt to edit a published version	Create a draft
OrkenaError.EVAL_FAILED	The eval gate did not pass	Improve the version or the suite
OrkenaError.PACK_SYNTAX	The policy pack has a syntax error	Fix per the grammar

Ledger and bundles#

Code	Meaning	Fix
OrkenaError.BUNDLE_VERIFY_FAILED	Verification failed — hash mismatch at seq	The archive was altered; re-export
OrkenaError.ANCHOR_INVALID	An anchor signature is invalid	Contact support; this is serious
OrkenaError.EXPORT_SCOPE_EMPTY	The export scope has no events	Widen the scope

Kill switch#

Code	Meaning	Fix
OrkenaError.KILL_REASON_REQUIRED	A kill needs a reason	Pass --reason
OrkenaError.KILL_ALREADY_ACTIVE	A kill is already in effect at this level	Check the incident state

Every error that touches the record is itself a ledger event. Gate errors are explained alongside the setup flow in HITL gates and four-eyes; bundle errors alongside Evidence bundles; the full endpoint list is in the API reference.