CASCAQitError¶
from cascaqit import CASCAQitError
CASCAQitError ¶
CASCAQitError(
message: str,
*,
code: str | None = None,
stage: str | None = None,
object_path: str | None = None,
suggestion: str | None = None,
retryable: bool | None = None,
error_id: str | None = None,
trace_references: dict[str, Any] | None = None,
source_hashes: dict[str, Any] | None = None,
metadata: dict[str, Any] | None = None,
diagnostics: tuple[DiagnosticsIR, ...] = (),
cause: BaseException | None = None,
)
Base class for structured SDK exceptions. Catch it to handle ProgramValidationError, CapabilityError and BackendExecutionError together. Some direct constructor checks still raise ordinary Python TypeError or ValueError, so this base class does not cover every invalid input.
Message is the readable explanation; prefer code for automated handling. Stage identifies the failing phase, object_path points to a field, suggestion provides corrective guidance, and retryable indicates suitability for a retry policy. Error_id can be explicit or derived from category and code; it is not a unique occurrence ID. trace_references, source_hashes, metadata and diagnostics retain context; cause may retain the underlying exception. Metadata is redacted according to SDK rules.
The base defaults to category=unknown, code=CASCAQIT_ERROR, severity=error and retryable=False, with no default stage or suggestion. Subclasses override relevant defaults. Constructing an exception does not raise it or initiate a retry.
from cascaqit import CASCAQitError, ProgramValidationError
try:
raise ProgramValidationError("theta is outside bounds", code="THETA_RANGE")
except CASCAQitError as error:
assert error.code == "THETA_RANGE"
assert error.to_error_ir().category == "validation"
assert error.to_diagnostic().code == "THETA_RANGE"
See Results and diagnostics for troubleshooting real runs.
Return ErrorIR retaining category, code, message, retry flag, diagnostics and source references. A supplied cause contributes its type and message. Conversion does not rerun the failed task.
Return a DiagnosticsIR view retaining code, message, object_path and suggestion, with stage and severity mapped to diagnostic rules. This is a summary projection; use to_error_ir for the full error context.