Package: aic-sdk==3.2.0. Core SDK: 0.24.0. Source: Python wrapper 3.2.0.
Every SDK exception below subclasses Exception directly. There is no shared SDK base exception. Catch the specific errors you can recover from. Native failures from model loading, constructors, initialization, processing, parameter control, token updates and analysis are mapped to these classes.
Every class accepts message: str and exposes a read-only message: str property. ModelDownloadError and UnknownError require one additional constructor argument, shown below. The inherited args, str() and traceback behavior comes from Python’s Exception.
Python argument conversion can instead raise TypeError for an incorrect NumPy dtype or dimension, or OverflowError for integers outside the native unsigned range. A noncontiguous one-dimensional float32 view is accepted and normalized by the wrapper. Wrong block length is a separate SDK error. Async methods can raise conversion errors when called and SDK errors when awaited. Background download task failure can raise RuntimeError.
A Python processing exception returns no output array. The wrapper discards its local output on an SDK error, even if the underlying C processor writes fallback samples. Choose and implement your application fallback explicitly.
License and authorization
Cause: The SDK key or JWT is malformed, empty or contains a NUL character.
Recovery: Check that you copied the complete credential without extra characters. Read it from your approved secret source; do not print it.
message: str (read-only): Human-readable diagnostic text.
LicenseExpiredError
Cause: The credential has expired.
Recovery: Renew it. For a session originally created with a JWT, update the bearer token before expiry. Recreate the session when token replacement is unsupported.
message: str (read-only): Human-readable diagnostic text.
LicenseVersionUnsupportedError
Cause: The credential format version is unsupported by this SDK.
Recovery: Use a compatible released SDK and credential, or contact support.
message: str (read-only): Human-readable diagnostic text.
TokenUnsupportedError
Cause: Token replacement is only supported when the original credential and replacement are both JWTs.
Recovery: Use a JWT from initial session creation if rotation is required. The rejected replacement is not installed; recreate the session when changing credential type.
message: str (read-only): Human-readable diagnostic text.
ProcessingNotAllowedError
Cause: Authorization or usage reporting failed, or the session was terminated. This can occur after successful initialization.
Recovery: Check the credential and required network access. Keep handling this error in the processing loop. A terminated session requires a new processor, detector or analyzer; a reset does not reopen it.
message: str (read-only): Human-readable diagnostic text.
Model files
ModelInvalidError
Cause: The model file is malformed or incomplete.
Recovery: Download the model again and verify the local file.
message: str (read-only): Human-readable diagnostic text.
ModelVersionUnsupportedError
Cause: The model file format is incompatible with the installed core SDK.
Recovery: Use Model.download() with the installed SDK to select compatible data. Compare get_compatible_model_version() when diagnosing a manually supplied file.
message: str (read-only): Human-readable diagnostic text.
ModelTypeUnsupportedError
Cause: The model type does not match the operation.
Recovery: Use an enhancement model for Processor, a dedicated VAD model for Vad and a Tyto analysis model for analyzer_pair or FileAnalyzer.
message: str (read-only): Human-readable diagnostic text.
ModelDataUnalignedError
Cause: Native model data does not satisfy the required 64-byte alignment.
Recovery: Python exposes file loading rather than raw buffer loading. Use Model.from_file(); report this error with package and platform details if it occurs through that path.
message: str (read-only): Human-readable diagnostic text.
ModelDownloadError
Cause: Manifest retrieval, model selection, download, verification or writing the destination failed.
Recovery: Inspect details, check the model ID, network access and destination permissions, then retry the download.
message: str (read-only): Human-readable diagnostic text.
details: str (read-only): Underlying download failure details.
FileSystemError
Cause: The model file cannot be opened or read.
Recovery: Check that the path exists, is a model file and is readable.
message: str (read-only): Human-readable diagnostic text.
FilePathInvalidError
Cause: The native file path is invalid.
Recovery: Use a valid path without embedded NUL characters. In aic-sdk 3.2.0 a NUL path can escape normal SDK exception conversion; validate it before calling Model.from_file().
message: str (read-only): Human-readable diagnostic text.
Audio configuration and state
AudioConfigUnsupportedError
Cause: The native sample rate or block configuration is unsupported. FileAnalyzer also rejects sample_rate=0 and step_samples=0.
Recovery: Start with ProcessorConfig.optimal(model), then initialize. Native input rates are 8,000–192,000 Hz; use a positive block size and a configuration supported by the model.
message: str (read-only): Human-readable diagnostic text.
AudioConfigMismatchError
Cause: The number of samples differs from the initialized fixed size or exceeds the maximum variable size.
Recovery: Use exactly config.block_size mono samples, or a block of up to that size with variable_block_size=True. A wrong dtype or dimension raises Python TypeError instead.
message: str (read-only): Human-readable diagnostic text.
NotInitializedError
Cause: Processing or buffering was attempted before initialization.
Recovery: Pass config to the processor or detector constructor, or call initialize/initialize_async. Initialize the Collector before buffer().
message: str (read-only): Human-readable diagnostic text.
ParameterOutOfRangeError
Cause: A parameter value lies outside its supported range.
Recovery: Use the bounds on ProcessorParameter or VadParameter. Read the current value with get_parameter(); do not infer model-specific defaults.
message: str (read-only): Human-readable diagnostic text.
ParameterFixedError
Cause: Compatibility exception retained in the Python public surface. The 3.2.0 error mapper does not emit it.
Recovery: Keep it only where existing application code requires the type; current parameter validation uses ParameterOutOfRangeError.
message: str (read-only): Human-readable diagnostic text.
Internal
InternalError
Cause: A native internal operation failed. A NUL-containing OtelConfig.session_id also maps to this error during processor or detector construction.
Recovery: First check the supplied session ID. For other failures, retain package/core versions and a minimal reproduction and contact support; omit credentials.
message: str (read-only): Human-readable diagnostic text.
UnknownError
Cause: The native SDK returned an error code not recognized by this wrapper.
Recovery: Record error_code and package/core versions, then report a minimal reproduction without credentials.
message: str (read-only): Human-readable diagnostic text.
error_code: int (read-only): Signed 32-bit native error code.
Handling an error
This example exercises a local file error without a model download or SDK credential:
See the Python API index and Python guide. 
