Skip to content

Errors

Exception hierarchy for QLAM Core.

Error classes and exit codes for qlam-core.

APIError 

APIError(message: str = 'API error', status_code: int | None = None, response_data: Any | None = None, exit_code: int = ExitCode.UNKNOWN_ERROR)

Bases: QlamCoreError


              flowchart TD
              qlam_core.errors.APIError[APIError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.APIError
                


              click qlam_core.errors.APIError href "" "qlam_core.errors.APIError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when a backend API returns an error response (HTTP status >= 400).

Source code in qlam_core/errors/errors.py 
65
66
67
68
69
70
71
72
73
74
def __init__(
    self,
    message: str = "API error",
    status_code: int | None = None,
    response_data: Any | None = None,
    exit_code: int = ExitCode.UNKNOWN_ERROR,
) -> None:
    super().__init__(message, exit_code)
    self.status_code = status_code
    self.response_data = response_data

AuthConfigurationError 

AuthConfigurationError(message: str = 'Authentication configuration error', exit_code: int = ExitCode.AUTH_CONFIG_ERROR)

Bases: ConfigurationError


              flowchart TD
              qlam_core.errors.AuthConfigurationError[AuthConfigurationError]
              qlam_core.errors.errors.ConfigurationError[ConfigurationError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.ConfigurationError --> qlam_core.errors.AuthConfigurationError
                                qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.errors.ConfigurationError
                



              click qlam_core.errors.AuthConfigurationError href "" "qlam_core.errors.AuthConfigurationError"
              click qlam_core.errors.errors.ConfigurationError href "" "qlam_core.errors.errors.ConfigurationError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when an authentication provider is misconfigured.

Source code in qlam_core/errors/errors.py 
54
55
56
57
58
59
def __init__(
    self,
    message: str = "Authentication configuration error",
    exit_code: int = ExitCode.AUTH_CONFIG_ERROR,
) -> None:
    super().__init__(message, exit_code)

AuthenticationError 

AuthenticationError(message: str = 'Authentication failed', exit_code: int = ExitCode.AUTH_ERROR)

Bases: QlamCoreError


              flowchart TD
              qlam_core.errors.AuthenticationError[AuthenticationError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.AuthenticationError
                


              click qlam_core.errors.AuthenticationError href "" "qlam_core.errors.AuthenticationError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when authentication fails (credentials rejected, expired, etc.).

Source code in qlam_core/errors/errors.py 
36
37
38
39
def __init__(
    self, message: str = "Authentication failed", exit_code: int = ExitCode.AUTH_ERROR
) -> None:
    super().__init__(message, exit_code)

ConfigurationError 

ConfigurationError(message: str = 'Configuration error', exit_code: int = ExitCode.USAGE_ERROR)

Bases: QlamCoreError


              flowchart TD
              qlam_core.errors.ConfigurationError[ConfigurationError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.ConfigurationError
                


              click qlam_core.errors.ConfigurationError href "" "qlam_core.errors.ConfigurationError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when there's an issue with configuration.

Source code in qlam_core/errors/errors.py 
45
46
47
48
def __init__(
    self, message: str = "Configuration error", exit_code: int = ExitCode.USAGE_ERROR
) -> None:
    super().__init__(message, exit_code)

ExitCode

Bases: IntEnum


              flowchart TD
              qlam_core.errors.ExitCode[ExitCode]

              

              click qlam_core.errors.ExitCode href "" "qlam_core.errors.ExitCode"

Exit codes for qlam-core errors.

from_http_status classmethod 

from_http_status(status_code: int) -> 'ExitCode'

Map HTTP status codes to exit codes.

Source code in qlam_core/errors/exit_codes.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
@classmethod
def from_http_status(cls, status_code: int) -> "ExitCode":
    """Map HTTP status codes to exit codes."""
    if 200 <= status_code < 300:
        return cls.SUCCESS
    if status_code in (401, 403):
        return cls.AUTH_ERROR
    if status_code == 404:
        return cls.NOT_FOUND_ERROR
    if status_code == 409:
        return cls.CONFLICT_ERROR
    if status_code == 422:
        return cls.VALIDATION_ERROR
    if 500 <= status_code < 600:
        return cls.SERVER_ERROR
    return cls.UNKNOWN_ERROR

get_description classmethod 

get_description(exit_code: int) -> str

Get a human-readable description of an exit code.

Source code in qlam_core/errors/exit_codes.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@classmethod
def get_description(cls, exit_code: int) -> str:
    """Get a human-readable description of an exit code."""
    descriptions = {
        cls.SUCCESS: "Success",
        cls.USAGE_ERROR: "Usage/validation error",
        cls.NETWORK_ERROR: "Network timeout/unavailable (DNS/TLS/connect/timeout)",
        cls.AUTH_CONFIG_ERROR: "Authentication configuration error (missing/invalid auth settings)",
        cls.AUTH_ERROR: "Authentication error (401/403)",
        cls.VALIDATION_ERROR: "Validation/unprocessable entity error (422)",
        cls.NOT_FOUND_ERROR: "Not found error (404)",
        cls.CONFLICT_ERROR: "Conflict error (409)",
        cls.SERVER_ERROR: "Server error (5xx)",
        cls.UNKNOWN_ERROR: "Unknown/unexpected error",
        cls.INTERRUPTED: "Interrupted by user (SIGINT)",
    }
    try:
        return descriptions.get(ExitCode(exit_code), f"Unknown exit code: {exit_code}")
    except ValueError:
        return f"Unknown exit code: {exit_code}"

FileSystemError 

FileSystemError(message: str = 'File system error', exit_code: int = ExitCode.UNKNOWN_ERROR)

Bases: QlamCoreError


              flowchart TD
              qlam_core.errors.FileSystemError[FileSystemError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.FileSystemError
                


              click qlam_core.errors.FileSystemError href "" "qlam_core.errors.FileSystemError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when file system operations fail.

Source code in qlam_core/errors/errors.py 
 98
 99
100
101
def __init__(
    self, message: str = "File system error", exit_code: int = ExitCode.UNKNOWN_ERROR
) -> None:
    super().__init__(message, exit_code)

NetworkError 

NetworkError(message: str = 'Network error', exit_code: int = ExitCode.NETWORK_ERROR)

Bases: QlamCoreError


              flowchart TD
              qlam_core.errors.NetworkError[NetworkError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.NetworkError
                


              click qlam_core.errors.NetworkError href "" "qlam_core.errors.NetworkError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when network operations fail.

Source code in qlam_core/errors/errors.py 
89
90
91
92
def __init__(
    self, message: str = "Network error", exit_code: int = ExitCode.NETWORK_ERROR
) -> None:
    super().__init__(message, exit_code)

QlamCoreError 

QlamCoreError(message: str, exit_code: int = ExitCode.UNKNOWN_ERROR)

Bases: Exception


              flowchart TD
              qlam_core.errors.QlamCoreError[QlamCoreError]

              

              click qlam_core.errors.QlamCoreError href "" "qlam_core.errors.QlamCoreError"

Base exception for qlam-core errors.

Contract: - Always carries a user-facing message. - Always carries a stable exit code suitable for application boundaries.

Library code may raise these errors to request specific UX and exit-code behavior from consumer applications.

Source code in qlam_core/errors/errors.py 
27
28
29
30
def __init__(self, message: str, exit_code: int = ExitCode.UNKNOWN_ERROR) -> None:
    super().__init__(message)
    self.message = message
    self.exit_code = int(exit_code)

ValidationError 

ValidationError(message: str = 'Validation error', exit_code: int = ExitCode.VALIDATION_ERROR)

Bases: QlamCoreError


              flowchart TD
              qlam_core.errors.ValidationError[ValidationError]
              qlam_core.errors.errors.QlamCoreError[QlamCoreError]

                              qlam_core.errors.errors.QlamCoreError --> qlam_core.errors.ValidationError
                


              click qlam_core.errors.ValidationError href "" "qlam_core.errors.ValidationError"
              click qlam_core.errors.errors.QlamCoreError href "" "qlam_core.errors.errors.QlamCoreError"

Raised when input validation fails.

Source code in qlam_core/errors/errors.py 
80
81
82
83
def __init__(
    self, message: str = "Validation error", exit_code: int = ExitCode.VALIDATION_ERROR
) -> None:
    super().__init__(message, exit_code)