uniqc.exceptions module

Custom exceptions for UnifiedQuantum.

This module is the single source of truth for all custom exceptions in the package. Sub-modules re-export from here so that legacy import paths continue to work, but every exception class is defined in this file.

Exception hierarchy:

UnifiedQuantumError
├── AuthenticationError
├── InsufficientCreditsError
├── QuotaExceededError
├── NetworkError
├── TaskFailedError
├── TaskTimeoutError
├── TaskNotFoundError
├── BackendError
│   ├── BackendNotAvailableError
│   └── BackendNotFoundError
├── CircuitError
│   ├── CircuitTranslationError
│   ├── UnsupportedGateError
│   ├── NotSupportedGateError
│   ├── RegisterNotFoundError
│   ├── RegisterOutOfRangeError
│   ├── RegisterDefinitionError
│   ├── NotMatrixableError
│   └── TimelineDurationError
├── ConfigError
│   ├── ConfigValidationError
│   ├── PlatformNotFoundError
│   └── ProfileNotFoundError
├── CompilationFailedError
├── TopologyError
├── StaleCalibrationError
├── BackendOptionsError  (also ValueError)
└── MissingDependencyError  (also ImportError)

exception uniqc.exceptions.AuthenticationError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when authentication fails (invalid token, expired credentials, etc.).

This error indicates that the provided API token or credentials are invalid, expired, or do not have the required permissions.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.BackendError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when a backend operation fails.

This is the base class for all backend-related errors.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.BackendNotAvailableError(message, *, details=None, hint_key=None)

Bases: BackendError

Raised when a backend is not available.

This error indicates that the backend is offline, not configured, or cannot be accessed due to missing dependencies.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.BackendNotFoundError(message, *, details=None, hint_key=None)

Bases: BackendError

Raised when a requested backend is not found.

This error indicates that the specified backend name is not registered in the backend registry.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.BackendOptionsError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError, ValueError

Raised when BackendOptions construction, validation, or normalisation fails.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.CircuitError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Base class for all circuit-related errors.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.CircuitTranslationError(message, *, source_format=None, target_format=None, details=None)

Bases: CircuitError

Raised when circuit translation or IR conversion fails.

This covers failures converting between OriginIR, OpenQASM 2, and other intermediate representations.

Parameters:

• message (str)

• source_format (str | None)

• target_format (str | None)

• details (dict | None)

Return type:

None

exception uniqc.exceptions.CompilationFailedError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when quantum circuit compilation fails.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.ConfigError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Base exception for configuration-related errors.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.ConfigValidationError(message, *, details=None, hint_key=None)

Bases: ConfigError

Raised when configuration validation fails.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.InsufficientCreditsError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when the account has insufficient credits to run a task.

This error indicates that the user’s account balance is too low to execute the requested quantum computation.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.MissingDependencyError(package, extra=None, install_hint=None)

Bases: UnifiedQuantumError, ImportError

Raised when an optional dependency is not installed.

Inherits from both UnifiedQuantumError and ImportError so that it can be caught by either.

Variables:

• package – The name of the missing package.

• extra – The pip extras name to install the package, if applicable.

• install_hint – An explicit install or recovery hint, if applicable.

Parameters:

• package (str)

• extra (str | None)

• install_hint (str | None)

Return type:

None

exception uniqc.exceptions.NetworkError(message, *, url=None, status_code=None, details=None)

Bases: UnifiedQuantumError

Raised when a network operation fails.

This error covers connection failures, timeouts, DNS errors, and other network-related issues when communicating with quantum computing backends.

Parameters:

• message (str)

• url (str | None)

• status_code (int | None)

• details (dict | None)

Return type:

None

exception uniqc.exceptions.NotMatrixableError(message, *, details=None, hint_key=None)

Bases: CircuitError

Raised when a circuit or gate has no unitary matrix representation.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.NotSupportedGateError(message, *, details=None, hint_key=None)

Bases: CircuitError

Raised when an unsupported gate is encountered in OpenQASM 2.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.PlatformNotFoundError(message, *, details=None, hint_key=None)

Bases: ConfigError

Raised when an unsupported platform is referenced.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.ProfileNotFoundError(message, *, details=None, hint_key=None)

Bases: ConfigError

Raised when a configuration profile is not found.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.QuotaExceededError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when the user has exceeded their usage quota.

This error indicates that the user has reached their daily, monthly, or total usage limit for the quantum computing service.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.RegisterDefinitionError(message, *, details=None, hint_key=None)

Bases: CircuitError

Raised when a register definition is invalid (e.g., duplicate name, empty).

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.RegisterNotFoundError(message, *, details=None, hint_key=None)

Bases: CircuitError

Raised when a quantum or classical register is not found.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.RegisterOutOfRangeError(message, *, details=None, hint_key=None)

Bases: CircuitError

Raised when a register index exceeds its defined size.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.StaleCalibrationError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when calibration data exceeds the allowed age (TTL).

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.TaskFailedError(message, *, task_id=None, backend=None, error_code=None, details=None)

Bases: UnifiedQuantumError

Raised when a quantum task fails on the backend.

This error indicates that the task was submitted successfully but failed during execution on the quantum computer or simulator.

Parameters:

• message (str)

• task_id (str | None)

• backend (str | None)

• error_code (str | None)

• details (dict | None)

Return type:

None

exception uniqc.exceptions.TaskNotFoundError(message, *, task_id=None, details=None)

Bases: UnifiedQuantumError

Raised when a task cannot be found.

This error indicates that the specified task ID does not exist or the user does not have permission to access it.

Parameters:

• message (str)

• task_id (str | None)

• details (dict | None)

Return type:

None

exception uniqc.exceptions.TaskTimeoutError(message, *, task_id=None, timeout=None, details=None)

Bases: UnifiedQuantumError

Raised when waiting for a task result exceeds the timeout.

This error indicates that the task did not complete within the specified timeout period. The task may still be running.

Parameters:

• message (str)

• task_id (str | None)

• timeout (float | None)

• details (dict | None)

Return type:

None

exception uniqc.exceptions.TimelineDurationError(message, *, details=None, hint_key=None)

Bases: CircuitError

Raised when a logical circuit cannot be scheduled without gate durations.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.TopologyError(message, *, details=None, hint_key=None)

Bases: UnifiedQuantumError

Raised when an invalid qubit or topology is used.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.UnifiedQuantumError(message, *, details=None, hint_key=None)

Bases: Exception

Base exception for all UnifiedQuantum errors.

Parameters:

• message (str)

• details (dict | None)

• hint_key (str | None)

Return type:

None

exception uniqc.exceptions.UnsupportedGateError(message, *, gate_name=None, backend=None, details=None)

Bases: CircuitError

Raised when a circuit contains an unsupported gate.

This error indicates that the target backend does not support one or more gates present in the circuit.

Parameters:

• message (str)

• gate_name (str | None)

• backend (str | None)

• details (dict | None)

Return type:

None