Exceptions

The Zentitle C++ SDK defines a structured hierarchy of exception classes to help developers identify and handle errors effectively. Below is an overview of the most common exceptions when integrating or using the SDK.

SDKException

This is the base class for all SDK-specific exceptions. It inherits from std::runtime_error and is used for general-purpose errors encountered during licensing operations.

StateException

Raised when an operation is attempted that violates the current activation state. For example, calling refreshLease() When the activation is not in a valid state for that action.

IllegalActivationOperationException

This is a more specific state-related exception thrown when a licensing method is explicitly disallowed in the current activation state. It indicates misuse of the SDK's activation lifecycle methods.

DataValidationException

This exception is thrown when internal data fails validation, such as malformed configuration data, invalid license file contents, or corrupted persistent state. It helps catch structural and semantic issues in the inputs.

FeatureNotFoundException

Raised when a requested feature (by key) is not found within the current license. This is typically thrown when using the features() interface and attempting to retrieve a non-existent or unavailable feature.

HttpRequestException

This exception originates from low-level HTTP communication errors, such as unreachable endpoints, connection timeouts, or other transport-level issues. It does not indicate API logic errors, only communication problems.

LicensingApiException with ApiError

Thrown when the Licensing API returns an error response with a non-success status code. This exception provides access to the raw response, including HTTP status, error message, and headers.

LicensingApiException can contain a parsed ApiError object. This object includes detailed information from the Licensing API, such as the error code, message, and field-level validation errors. It allows applications to implement more granular error handling based on the error structure returned by the server.