Exceptions

All exceptions live in arclasp.exceptions. The base class is ArclaspPolicyError; catching it catches every policy-related exception the SDK raises. A few exceptions extend Exception directly when they’re not policy decisions (timeouts, backend connectivity, auto-pause).

ArclaspPolicyError                # base for policy-driven exceptions
├── ActionDeniedError               # policy denied an action or human reviewer denied it
├── PolicyViolationError            # a policy condition was violated outside the normal evaluation path
└── ArclaspKillSwitchError        # org-wide kill switch denied the action

Exception
├── BackendUnavailableError         # the backend is unreachable and fail-mode is deny
├── ChainTimeoutError               # the chain ran past its configured timeout
└── ChainAutoPausedError            # an auto-pause rule (event count, duration, token budget) fired

Catch ArclaspPolicyError when you want to handle every policy-driven denial uniformly:

import arclasp
from arclasp.exceptions import ArclaspPolicyError

try:
    async with arclasp.Chain("workflow") as chain:
        await chain.record_agent_action(...)
except ArclaspPolicyError as exc:
    logger.error(f"Policy denied the action: {exc}")
    fallback_workflow()

For operational issues (backend down, chain timed out, runaway behavior auto-paused), catch the relevant Exception subclass instead.

`ActionDeniedError`

Raised when a policy denies an action, when a human reviewer denies an approval, or when the backend marks a pending approval as timed out. Backend unavailability is a separate case — see BackendUnavailableError below.

class ActionDeniedError(ArclaspPolicyError):
    message: str
    policy_name: str | None
    condition: str | None
    chain_context: dict | None
    remediation: str | None
    docs_url: str | None
    decision_source: str | None

Attributes

Attribute	Description
`message`	Human-readable summary of why the action was denied.
`policy_name`	Which policy made the decision (default policy name or custom policy name).
`condition`	What about the action triggered the denial — the policy’s `decision_reason`, the approver’s notes, or a timeout message like `"Approval was not resolved within the configured timeout window."`
`chain_context`	Dict containing chain-level context. Includes `chain_id` and other state at the point of denial.
`remediation`	Suggested fix (e.g., `"update cumulative_financial_threshold_usd in init() or approve via dashboard"`).
`docs_url`	Link to the relevant docs page for this kind of denial.
`decision_source`	Where the decision came from: `"backend_evaluation"` for a direct policy decision, or `"human_approval"` once a `require_approval` gate has been resolved by a reviewer (approved, denied, or backend-side timed out).

Distinguishing denial reasons

ActionDeniedError doesn’t have a single reason enum. To tell what kind of denial occurred, check decision_source and condition together:

Scenario	`decision_source`	`condition`
Policy denied at the backend	`"backend_evaluation"`	Policy’s `decision_reason`
Human reviewer clicked Deny	`"human_approval"`	The reviewer’s notes
Approval expired on the backend side without a decision	`"human_approval"`	Timeout condition text
The SDK’s own local polling window expired first	—	Raises `ChainTimeoutError` instead, not `ActionDeniedError`

Example

from arclasp.exceptions import ActionDeniedError

try:
    await chain.record_agent_action(
        agent_name="commitment-agent",
        action_type="tool_call",
        action_name="record_purchase",
        payload={"amount_usd": 75000},
    )
except ActionDeniedError as exc:
    print(f"Policy: {exc.policy_name}")
    print(f"Condition: {exc.condition}")
    print(f"What to do: {exc.remediation}")
    print(f"Docs: {exc.docs_url}")
    print(f"Chain context: {exc.chain_context}")

    if exc.decision_source == "human_approval":
        if exc.condition and "not resolved within" in exc.condition:
            # No reviewer responded — retry tomorrow
            schedule_retry()
        else:
            # Reviewer explicitly denied with notes in `condition`
            chain_id = (exc.chain_context or {}).get("chain_id")
            escalate_to_manual_review(chain_id)
    else:
        # Policy denial at the backend
        log_policy_denial(exc)

Don’t suppress and continue

Suppressing ActionDeniedError and retrying the same action accomplishes nothing — the policy will deny it again. If you catch it, either:

Change the situation (lower amount, different recipient, different agent) and retry
Escalate the work to a human
Log the denial and continue with the next part of your workflow

The message, remediation, and docs_url fields are built to be shown to your application’s user — they tell a human reading logs what to do.

`PolicyViolationError`

Raised when a policy condition is violated outside the normal action-decision path — for example, when chain-level cumulative limits are checked at chain start or during background reconciliation rather than at an individual action evaluation. Inherits from ArclaspPolicyError. In practice, most application code can catch ArclaspPolicyError to handle this and ActionDeniedError uniformly.

`ArclaspKillSwitchError`

Raised when the organization’s kill switch is active and an action is attempted.

class ArclaspKillSwitchError(ArclaspPolicyError):
    message: str
    organization_id: str | None
    reason: str | None

When raised

Whenever the kill switch is on for your org and record_agent_action is called. This is distinct from a regular ActionDeniedError so applications can show a different message (maintenance mode vs. policy violation).

Attributes

Attribute	Description
`message`	Default: `"All agent actions are denied: organisation kill switch is active"`.
`organization_id`	The org the kill switch applies to.
`reason`	The reason the admin gave when activating the kill switch.

Example

from arclasp.exceptions import ArclaspKillSwitchError

try:
    async with arclasp.Chain("workflow") as chain:
        await chain.record_agent_action(...)
except ArclaspKillSwitchError as exc:
    return {
        "status": "maintenance",
        "message": "Agent activity is temporarily paused.",
        "reason": exc.reason,
    }

See Kill switch for activation and resumption.

`BackendUnavailableError`

Raised when the SDK can’t reach the backend after retries (max_retries, backend_timeout_seconds) or the backend keeps returning 5xx/429. Inherits from Exception, not ArclaspPolicyError — it’s an operational issue, not a policy decision. This is always raised on backend unavailability, regardless of fail_mode / fail_modes. fail_mode="allow" is accepted for call-signature compatibility but is deprecated and has no effect — it emits a DeprecationWarning and the SDK still fails closed. There is no local buffering or “proceed and sync later” behavior in governed execution; the action simply did not run.

Example

from arclasp.exceptions import BackendUnavailableError

try:
    await chain.record_agent_action(...)
except BackendUnavailableError as exc:
    logger.warning(f"Arclasp backend unreachable: {exc}")
    # The action did NOT execute. Decide whether to retry, defer, or fail the workflow.
    queue_for_retry()

`ChainTimeoutError`

Raised when a chain exceeds its configured runtime without completing. Inherits from Exception. Long-running batch workflows should configure a longer timeout via SDK config. The exception is meant to catch chains that have hung — not chains that are doing legitimate long work.

`ChainAutoPausedError`

Raised when a chain hits one of the auto-pause limits — event count, chain duration, or token budget. Inherits from Exception. See Policies for the default auto-pause thresholds.

Example

from arclasp.exceptions import ChainAutoPausedError

try:
    await chain.record_agent_action(...)
except ChainAutoPausedError as exc:
    # The chain has stopped to prevent runaway behavior
    logger.error(f"Chain auto-paused: {exc}")
    investigate_chain(chain.id)

Transport and setup errors

Not every failure is a policy decision. Two plain-Exception cases come from lower in the stack:

RuntimeError — raised by the SDK itself for setup mistakes: calling any Chain method before arclasp.init(), or before entering the chain as a context manager ("Chain has not been started. Use it as a context manager."), or using synchronous with Chain(...) from inside a running async event loop.
httpx.HTTPStatusError — raised directly (not wrapped) on 4xx responses, since those are deterministic client errors that retrying won’t fix. The two you’ll see most: 401 (missing or invalid API key) and 403 (the key’s role doesn’t have permission for that operation).

Troubleshooting

Hosted example accidentally hitting localhost. backend_url defaults to http://localhost:8000. If you copied an example without adding backend_url="https://api.proofrail.dev", every call will fail to connect — you’ll see a connection error surface as BackendUnavailableError after retries are exhausted, not a clean “wrong URL” message. Check your arclasp.init() call first. 401 — missing or invalid API key. httpx.HTTPStatusError with status_code=401. Confirm ARCLASP_API_KEY is set and that the key hasn’t been revoked from the dashboard. 403 — role/permission problem. httpx.HTTPStatusError with status_code=403. The authenticated key or user doesn’t have the role required for that endpoint (e.g., approving requires the approver role). Approval still pending / terminal waiting. This is expected while record_agent_action() blocks on a require_approval decision — it polls every 5 seconds. Open the dashboard’s /dashboard/approvals and resolve the pending item; the terminal resumes on the next poll after you do. Approval denied. record_agent_action() raises ActionDeniedError with decision_source="human_approval" and the reviewer’s notes in condition. Approval timed out. Either ActionDeniedError (the backend marked the approval as timed out) or ChainTimeoutError (the SDK’s own local polling window, default_approval_timeout_hours, expired first). See Distinguishing denial reasons above.

Handling patterns

Catch all policy denials, distinguish by source

from arclasp.exceptions import (
    ArclaspPolicyError,
    ActionDeniedError,
    ArclaspKillSwitchError,
    BackendUnavailableError,
)

try:
    async with arclasp.Chain("workflow") as chain:
        await chain.record_agent_action(...)
except ArclaspKillSwitchError as exc:
    show_maintenance_mode(exc)
except ActionDeniedError as exc:
    handle_denial(exc)
except BackendUnavailableError as exc:
    queue_for_retry()
except ArclaspPolicyError as exc:
    # Catch-all for any other policy issues
    log_and_fail_gracefully(exc)

Distinguish human denial from timeout

try:
    await chain.record_agent_action(...)
except ActionDeniedError as exc:
    if exc.decision_source == "human_approval":
        if exc.condition and "not resolved within" in exc.condition:
            # No reviewer responded — retry tomorrow
            queue_for_retry(chain.id)
        else:
            # Reviewer explicitly denied
            notify_workflow_owner(exc)
    else:
        # Policy denial (not human)
        log_policy_block(exc)

Log denials for analytics

try:
    await chain.record_agent_action(...)
except ActionDeniedError as exc:
    metrics.increment(
        "arclasp.denial",
        tags={
            "policy": exc.policy_name or "unknown",
            "source": exc.decision_source or "unknown",
        },
    )
    raise  # re-raise after logging

Tracking which policies deny most often is a strong signal for what to revisit — either the policy is wrong, the workflow is wrong, or the thresholds need adjusting.

Don’t catch what you can’t fix

ArclaspKillSwitchError and ChainAutoPausedError shouldn’t be caught and worked around in normal application code:

ArclaspKillSwitchError is an admin saying “stop everything”. Honor it; don’t bypass.
ChainAutoPausedError means runaway behavior was detected. Stop and investigate; don’t retry blindly.

ActionDeniedError is the exception you’d routinely catch in application logic. BackendUnavailableError is the one to catch when you need explicit retry or queue handling.

Where to go next

SDK API

Type signatures for everything else.

Configuration

The init() options that drive these errors.

Human approval

Where approval-related denials come from.

Kill switch

Activating, resuming, and handling in code.

​Exceptions

​ActionDeniedError

​Attributes

​Distinguishing denial reasons

​Example

​Don’t suppress and continue

​PolicyViolationError

​ArclaspKillSwitchError

​When raised

​Attributes

​Example

​BackendUnavailableError

​Example

​ChainTimeoutError

​ChainAutoPausedError

​Example

​Transport and setup errors

​Troubleshooting

​Handling patterns

​Catch all policy denials, distinguish by source

​Distinguish human denial from timeout

​Log denials for analytics

​Don’t catch what you can’t fix

​Where to go next

SDK API

Configuration

Human approval

Kill switch

Exceptions

`ActionDeniedError`

Attributes

Distinguishing denial reasons

Example

Don’t suppress and continue

`PolicyViolationError`

`ArclaspKillSwitchError`

When raised

Attributes

Example

`BackendUnavailableError`

Example

`ChainTimeoutError`

`ChainAutoPausedError`

Example

Transport and setup errors

Troubleshooting

Handling patterns

Catch all policy denials, distinguish by source

Distinguish human denial from timeout

Log denials for analytics

Don’t catch what you can’t fix

Where to go next