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,
)
SDK 结构化异常的基类，可用于统一捕获 ProgramValidationError、CapabilityError 和 BackendExecutionError。部分直接构造校验仍使用 Python 的 TypeError 或 ValueError，因此捕获这个基类不等于覆盖所有错误输入。
message 是可读错误说明；自动处理应优先读取 code。stage 表示发生阶段，object_path 指向问题字段，suggestion 给出处理建议，retryable 标记是否适合按重试策略处理。error_id 可显式指定，默认由类别和 code 生成，它不是每次异常发生的唯一事件 ID。trace_references、source_hashes、metadata、diagnostics 保存关联信息；cause 可保留底层异常。metadata 会按 SDK 规则隐藏敏感字段。
基类默认 category=unknown、code=CASCAQIT_ERROR、severity=error、retryable=False，stage 和 suggestion 默认未设置。子类会替换相应默认值。构造异常不会自行抛出它，也不会自动重试。
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"
真实错误排查见结果与诊断。
返回 ErrorIR，保留类别、错误码、说明、重试标记、诊断和来源引用；如果有 cause，还记录其类型及消息。转换不会重新执行失败的任务。
返回 DiagnosticsIR 视图，保留 code、message、object_path 和 suggestion，并按诊断规则转换阶段与严重程度。它是摘要投影；需要完整错误上下文时使用 to_error_ir。