Exception Reference

Common exceptions

• ApprovalPending: the action needs human review and must not execute yet.
• ActionDenied: policy rejected the action and the worker must not execute it.
• ActionExpired: an approval window closed before execution.
• HaltStateConnectionError: the guard service could not be reached or timed out.
• HaltStateError: base class for HaltState SDK errors.

Handling rule

Catch approval and denial explicitly. For high-risk actions, treat unknown exceptions and connection errors as fail-closed unless the policy for that action explicitly permits degraded behavior.

Connection and auth errors

• HaltStateError: base error for SDK exceptions.
• HaltStateAuthError: invalid API key or tenant configuration.
• HaltStateConnectionError: network, timeout, or unreachable API.
• HaltStateRateLimitError: request rate limit exceeded.

Guard control-flow signals

• ApprovalPending: approval is still pending; scripts should exit cleanly and retry with the same idempotency key.
• ActionDenied: policy or human review rejected the action; do not retry as the same action.
• ActionExpired: approval window closed; create a fresh request only if business policy allows.

Fail-open versus fail-closed

Fail-closed is the default and the right posture for refunds, payments, PII, production writes, and customer communications. Fail-open may be acceptable only for low-risk actions where availability matters more than control, and that exception should be explicit in policy and incident documentation.

Implementation notes

Keep the HaltState call as close as possible to the side effect. The agent may plan and draft freely, but the wrapper around the actual action should be the place where authority is checked. That wrapper should send only the context required for policy evaluation: safe identifiers, normalized amounts, action names, risk flags, schedule windows, and redaction status. Raw customer payloads and secrets should stay in the business system or protected operator tooling.

Operational evidence

For each action, preserve the decision, the worker outcome, the idempotency key, safe resource references, latency, proof status, and redaction status. This evidence supports incident response and control narratives because it shows what the system did at runtime rather than only describing what the policy document intended. HaltState supports alignment work; it is not a substitute for legal advice or a compliance certification.