HaltState AI: Exception Reference

HaltState SDK uses exceptions to communicate approval states.

ApprovalPending

Raised when an action requires human approval before execution.

from haltstate import ApprovalPending

try:
    with client.guard(action="admin.delete", params={}, idempotency_key="..."):
        pass
except ApprovalPending as e:
    print(e.approval_id)  # UUID to track this request
    print(e.action)       # The action that needs approval
    sys.exit(0)           # Exit cleanly, retry later

ActionDenied

Raised when policy permanently blocks the action.

from haltstate import ActionDenied

try:
    with client.guard(action="forbidden.action", params={}, idempotency_key="..."):
        pass
except ActionDenied as e:
    print(str(e))         # Denial reason from policy
    print(e.policy_id)    # Which policy blocked it

ActionExpired

Raised when an approval request expired before being actioned.

from haltstate import ActionExpired

try:
    with client.guard(...):
        pass
except ActionExpired as e:
    print("Approval window closed - submit new request")
    # Generate a new idempotency key and retry

Connection Errors

from haltstate import (
    HaltStateConnectionError,
    HaltStateAuthError,
    HaltStateRateLimitError
)

try:
    with client.guard(...):
        execute()
except HaltStateAuthError:
    # Invalid API key or tenant
    log.error("Authentication failed - check credentials")
except HaltStateRateLimitError as e:
    # Too many requests
    log.warning(f"Rate limited, retry after {e.retry_after}s")
except HaltStateConnectionError:
    # Network issue
    if client.fail_open:
        execute()  # Proceed anyway (risky)
    else:
        raise  # Fail closed (safe default)

Fail Open vs Fail Closed

Configure behavior when HaltState is unreachable:

# Fail closed (default) - block action if can't reach HaltState
client = HaltStateClient(tenant_id="...", api_key="...", fail_open=False)

# Fail open - allow action if can't reach HaltState (use with caution)
client = HaltStateClient(tenant_id="...", api_key="...", fail_open=True)