Exceptions

The supported top-level SDK includes policy, availability, completion, timeout, auto-pause, kill-switch, and verification errors.

Supported top-level exception surface

ArclaspPolicyError
├── ActionDeniedError
└── ChainAutoPausedError

Exception
├── BackendUnavailableError
├── ChainCompletionError
├── ArclaspVerificationError
├── ChainTimeoutError
└── ArclaspKillSwitchError

The package can contain additional module-level compatibility/internal exception types. The table above is the supported top-level surface exported by arclasp.

`ActionDeniedError`

Raised when:

backend policy denies a governed action;
a human reviewer denies an Approval;
the backend resolves an Approval as timed out.

Useful fields can include:

message
policy_name
condition
chain_context
remediation
docs_url
decision_source

Example:

try:
    await chain.record_agent_action(
        agent_name="commitment-agent",
        action_type="tool_call",
        action_name="record_purchase",
        payload={"amount_usd": 75000},
    )
except arclasp.ActionDeniedError as exc:
    print(exc.policy_name)
    print(exc.condition)
    print(exc.decision_source)

Do not catch a denial and assume the same Chain remains writable. Denied/timed-out Chain states can block new governed events.

`ArclaspKillSwitchError`

Raised when the organization kill switch denies a governed action.

try:
    await chain.record_agent_action(...)
except arclasp.ArclaspKillSwitchError as exc:
    print("Governed action blocked by kill switch")
    print(exc.reason)

This error means the organization-wide Arclasp governance boundary is paused. It does not mean arbitrary customer code outside Arclasp has been remotely terminated.

`BackendUnavailableError`

Raised when governed execution cannot obtain an authoritative backend result after the SDK’s transport behavior is exhausted. The SDK fails closed. The current public SDK does not support fail_mode or fail_modes init() keywords. There is no fail-open SDK setting for governed execution.

try:
    await chain.record_agent_action(...)
except arclasp.BackendUnavailableError:
    queue_or_fail_workflow()

The protected customer-side action should not have run through that governed path.

`ChainTimeoutError`

This is the local approval polling timeout surface. It can occur when the SDK’s configured approval wait window expires before the backend returns a resolved approval. It is not the generic “Chain ran too long” exception. Backend-side approval timeout can instead surface as ActionDeniedError.

`ChainAutoPausedError`

Raised when the backend auto-pauses a Chain because a supported runaway-workflow limit has fired, such as event count, active duration, or token usage. Treat auto-pause as a stop-and-investigate condition. Do not blindly retry the same behavior.

`ChainCompletionError`

Raised when the SDK cannot confirm successful Chain completion. This matters because a receipt depends on valid completion.

try:
    async with arclasp.Chain("workflow") as chain:
        await chain.record_agent_action(...)
except arclasp.ChainCompletionError as exc:
    report_completion_failure(exc)

Do not claim a Chain Record exists if completion was not confirmed.

`ArclaspVerificationError`

Raised by supported verification helpers when verification cannot safely produce the requested result.

try:
    result = await arclasp.verify_receipt_v2("receipt-id")
except arclasp.ArclaspVerificationError as exc:
    handle_verification_failure(exc)

HTTP and setup errors

Some lower-level setup/client failures can still surface outside the Arclasp exception family, including invalid SDK usage and HTTP 4xx errors from deterministic client/auth failures. Common checks:

401: confirm the API key is present and active;
403: confirm the caller has the required organization role/scope;
local backend connection failure: pass backend_url="http://localhost:8000" only when intentionally developing against a local backend.

Approval timeout distinction

backend marks approval timed_out
        ->
ActionDeniedError

local SDK approval wait expires first
        ->
ChainTimeoutError

Remediation guidance

If a cumulative financial boundary is the problem, use the supported current control:

chain = arclasp.Chain("workflow")
chain.add_financial_threshold(usd=...)

Do not tell users to change cumulative_financial_threshold_usd in arclasp.init() as though it controls current backend-authoritative policy.

​Exceptions

​Supported top-level exception surface

​ActionDeniedError

​ArclaspKillSwitchError

​BackendUnavailableError

​ChainTimeoutError

​ChainAutoPausedError

​ChainCompletionError

​ArclaspVerificationError

​HTTP and setup errors

​Approval timeout distinction

​Remediation guidance