Source code for fastqsim.exceptions
"""
SDK-level exceptions for FastQSim.
All exceptions are raised from HTTP responses or job status codes returned
by the FastQubit API. Internal core errors (ParseError, UnsupportedBackend,
etc.) are never re-raised here — they appear as plain strings in
job.error_message when a job reaches FAILED status.
"""
# ---------------------------------------------------------------------------
# Base
# ---------------------------------------------------------------------------
[docs]
class FastQSimError(Exception):
"""Base exception for all FastQSim SDK errors."""
# ---------------------------------------------------------------------------
# Authentication / Access
# ---------------------------------------------------------------------------
[docs]
class AuthenticationError(FastQSimError):
"""Raised when the API token is invalid or expired (HTTP 401)."""
[docs]
class UnauthorizedAccessError(FastQSimError):
"""Raised when the authenticated user lacks permission for a resource (HTTP 403)."""
[docs]
class FastQSimConnectionError(FastQSimError):
"""Raised when the SDK cannot reach the FastQubit API endpoint."""
# ---------------------------------------------------------------------------
# Submission / Validation
# ---------------------------------------------------------------------------
[docs]
class ValidationError(FastQSimError):
"""Raised when the submitted circuit or parameters fail server-side validation (HTTP 422)."""
[docs]
class QuotaExceededError(FastQSimError):
"""Raised when the integrator's concurrency or monthly quota is exhausted (HTTP 402)."""
# ---------------------------------------------------------------------------
# Job lifecycle
# ---------------------------------------------------------------------------
[docs]
class JobFailedError(FastQSimError):
"""
Raised when a job reaches FAILED status.
Attributes:
job_id: The ID of the failed job.
reason: The worker error message, if available.
"""
def __init__(self, job_id: str, reason: str = ""):
self.job_id = job_id
self.reason = reason
msg = f"Job '{job_id}' failed on the server."
if reason:
msg += f" Reason: {reason}"
super().__init__(msg)
[docs]
class JobNotFoundError(FastQSimError):
"""Raised when a job_id does not exist on the server (HTTP 404)."""
def __init__(self, job_id: str):
self.job_id = job_id
super().__init__(f"Job '{job_id}' not found.")
[docs]
class JobTimeoutError(FastQSimError):
"""
Raised when polling exceeds the configured timeout before the job
reaches a terminal state.
Attributes:
job_id: The ID of the job that timed out.
timeout: The timeout in seconds that was exceeded.
"""
def __init__(self, job_id: str, timeout: int):
self.job_id = job_id
self.timeout = timeout
super().__init__(
f"Job '{job_id}' did not complete within {timeout} seconds."
)
[docs]
class JobNotCompleteError(FastQSimError):
"""
Raised when a result-retrieval method is called on a job that has not
yet reached a terminal state (e.g. still RUNNING or QUEUED).
"""
def __init__(self, job_id: str, current_status: str = ""):
self.job_id = job_id
self.current_status = current_status
msg = f"Job '{job_id}' has not completed yet."
if current_status:
msg += f" Current status: {current_status}"
super().__init__(msg)
[docs]
class JobCouldNotCancelError(FastQSimError):
"""
Raised when a cancellation request is rejected by the server
(e.g. the job has already completed or is in a non-cancellable state).
"""
def __init__(self, job_id: str, reason: str = ""):
self.job_id = job_id
self.reason = reason
msg = f"Job '{job_id}' could not be cancelled."
if reason:
msg += f" Reason: {reason}"
super().__init__(msg)
# ---------------------------------------------------------------------------
# Result retrieval
# ---------------------------------------------------------------------------
[docs]
class JobDoesNotContainCountsError(FastQSimError):
"""
Raised when get_counts() is called on a job that was run without
measurement shots (e.g. statevector-only simulation).
"""
# ---------------------------------------------------------------------------
# Device / API errors
# ---------------------------------------------------------------------------
[docs]
class InvalidDeviceTypeError(FastQSimError):
"""
Raised when an unsupported or invalid device type is specified (VAL_002).
Valid device types are: 'cpu', 'gpu', 'quantum'.
"""
[docs]
class APIError(FastQSimError):
"""
General API error (API_001).
Raised for unexpected server-side responses that do not map to a
more specific SDK exception.
"""