ShydaSHYDAPLATFORM
Vega SDK — Errors & Health API

Errors and Health API

Structured Capability errors with categories, severities, and retry hints — plus the Provider health-check result type.

Import

python
from vega_capability_sdk import (
    CancellationCapabilityError,
    CapabilityError,
    CapabilityHealthResult,
    CommunicationError,
    DependencyUnavailableError,
    ErrorCategory,
    ErrorSeverity,
    HardwareError,
    InvalidInputError,
    OutputValidationError,
    PreconditionFailedError,
    ProviderHealthStatus,
    ProviderInternalError,
    ResourceUnavailableError,
    SafetyRejectionError,
    TimeoutCapabilityError,
    UnsupportedOperationError,
)

CapabilityError

python
class CapabilityError(Exception):
    def __init__(
        self,
        message: str,
        *,
        error_code: str | None = None,
        retryable: bool | None = None,
        severity: ErrorSeverity | None = None,
        details: Mapping[str, Any] | None = None,
        cause: BaseException | None = None,
    ) -> None: ...


    def to_dict(self) -> dict[str, Any]: ...

Base class for expected Capability failures. details is frozen as a JSON-compatible mapping. to_dict() returns error_code, category,message, retryable, severity, and thawed details.

ErrorCategory and ErrorSeverity

ErrorCategory: invalid_input, precondition_failed,dependency_unavailable, resource_unavailable, hardware_error,communication_error, timeout, cancelled,safety_rejection, unsupported_operation,provider_internal_error, output_validation_failed.

ErrorSeverity: low, medium, high, critical.

Standard error subclasses

TermMeaning
InvalidInputErrorinvalid_input · retryable: No · medium
PreconditionFailedErrorprecondition_failed · retryable: Yes · medium
DependencyUnavailableErrordependency_unavailable · retryable: Yes · high
ResourceUnavailableErrorresource_unavailable · retryable: Yes · medium
HardwareErrorhardware_error · retryable: No · high
CommunicationErrorcommunication_error · retryable: Yes · high
TimeoutCapabilityErrortimeout · retryable: Yes · medium
CancellationCapabilityErrorcancelled · retryable: No · medium
SafetyRejectionErrorsafety_rejection · retryable: No · critical
UnsupportedOperationErrorunsupported_operation · retryable: No · medium
ProviderInternalErrorprovider_internal_error · retryable: No · high
OutputValidationErroroutput_validation_failed · retryable: No · medium

Health

ProviderHealthStatus: healthy, degraded,unhealthy, unknown.

python
@dataclass(frozen=True, slots=True)
class CapabilityHealthResult:
    status: ProviderHealthStatus
    checked_at: datetime
    message: str | None = None
    details: Mapping[str, Any] | None = None

checked_at must be timezone-aware and is normalized to UTC. Class methodshealthy, degraded, unhealthy, and unknowndefault checked_at to the current UTC time.

Examples

python
raise DependencyUnavailableError(
    "Speech service is unavailable",
    error_code="speech_backend_unavailable",
    details={"endpoint": "primary"},
)


health = CapabilityHealthResult.degraded(
    "Backend latency is elevated",
    details={"latency_ms": 850},
)
Do not put credentials, raw secret values, personal data, or unbounded backend responses inmessage or details.