IQMServerError

Module: iqm.station_control.interface.errors

class IQMServerError(*, message, error_code=None, source)

Bases: PydanticBase

Data transfer model for communicating error details over the REST API.

This model defines the structured JSON schema used to transport error details between components. It is used in both standard error response bodies (4xx/5xx) and within the ‘errors’ field of successful (200 OK) asynchronous job results.

This model acts as a data-carrying DTO (Data Transfer Object). High-level application code should map this model back into a raisable IQMError to represent the failure as a standard Python exception:

• Domain Logic: Errors carry a unique error_code (a stable machine-readable string) and a message (a human-readable description).

• Network Transmission: When crossing a network boundary (e.g., via REST), the exception is mapped to an HTTP status code. Only the base category subclass (like :class:`ValidationError`) is recoverable on the receiving end.

• Information Preservation: While the specific server-side class type (e.g., UnknownSettingError) is lost during transmission, the error_code and message attributes remain intact. This ensures the client receives full diagnostic information and can react to the specific failure code.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Attributes

detail	Human-readable description of the error.
model_config	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
message	Human-readable description of the error.
error_code	Optional machine-readable identifier for programmatic error handling.
source	Originating component or service of the error.

Methods

ensure_compatibility	Harmonizes differences between various service response formats.
from_exception	Factory method to create a DTO from an Exception.
raise_exception	Maps the error data to the appropriate IQMError and raises it.

Parameters:

• message (str)

• error_code (str | None)

• source (Literal['iqm-server', 'iqm-station-control'] | str)

message: str

Human-readable description of the error.

error_code: str | None

Optional machine-readable identifier for programmatic error handling.

source: Source

Originating component or service of the error.

property detail: str

Human-readable description of the error.

classmethod ensure_compatibility(data)

Harmonizes differences between various service response formats.

This handles both legacy fields (detail -> message) and transitional requirements (defaulting missing ‘source’ for older server versions).

Parameters:

data (Any)

Return type:

Any

raise_exception(status_code)

Maps the error data to the appropriate IQMError and raises it.

Parameters:

status_code (int)

Return type:

NoReturn

classmethod from_exception(exception, *, source)

Factory method to create a DTO from an Exception.

Parameters:

• exception (Exception)

• source (Literal['iqm-server', 'iqm-station-control'] | str)

Return type:

IQMServerError

model_config: ClassVar[ConfigDict] = {'extra': 'ignore', 'ser_json_inf_nan': 'constants', 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Inheritance