> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bioptimus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# bioptimus.observability.errors

Typed error codes and the unified SDK exception.

The SDK raises a single exception type, [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror), tagged with a machine-readable [`ErrorCode`](/sdk-reference/observability/errors#errorcode). Low-level code raises the typed error with structured `context`; this module owns the actionable remediation text for each code. The system boundary (for example the per-slide handler) logs it once with the attached code, so whoever reads the log gets an instant explanation and a direct fix.

Each [`ErrorCode`](/sdk-reference/observability/errors#errorcode) member carries two pieces of information:

* its value is the stable, dotted support code (for example `"BIO-WSI-001"`) used in logs, dashboards, and customer communication; and
* its name maps to a human-readable `event` slug (for example `"wsi_backend_unavailable"`) via [`ErrorCode.event`](/sdk-reference/observability/errors#event).

## ErrorCode

```python theme={null}
class ErrorCode(StrEnum)
```

Stable, machine-readable error codes for SDK failures.

The member value is the dotted support code embedded in logs and shared with customers. The member name doubles as a structured-log `event` slug through `event`.

***

#### event

```python theme={null}
@property
def event() -> str
```

Returns the structured-log event slug for this code.

**Returns**:

The lowercased member name, for example `"wsi_backend_unavailable"`.

***

#### remediation

```python theme={null}
@property
def remediation() -> str | None
```

Returns the central remediation hint for this code, if one exists.

***

#### remediation\_for

```python theme={null}
def remediation_for(code: ErrorCode | str) -> str | None
```

Returns the central remediation hint for an error code.

<ParamField body="code">
  An [`ErrorCode`](/sdk-reference/observability/errors#errorcode) member or its string value.
</ParamField>

**Returns**:

The remediation string when the code is known, otherwise `None`.

## BioptimusError

```python theme={null}
class BioptimusError(code: ErrorCode,
                     *,
                     message: str | None = None,
                     context: dict[str, Any] | None = None,
                     remediation: str | None = None)
```

Unified, typed exception raised across the SDK.

Wraps a machine-readable [`ErrorCode`](/sdk-reference/observability/errors#errorcode) together with structured diagnostic `context` and an actionable `remediation` hint. It is designed to be raised at low levels (`raise BioptimusError(...) from exc`) and logged exactly once at a system boundary.

***

#### to\_dict

```python theme={null}
def to_dict() -> dict[str, Any]
```

Returns the structured representation for logging or serialization.

**Returns**:

A mapping with the error code, event slug, message, context, and
remediation, suitable for inclusion in a structured log record.

## BioptimusValueError

```python theme={null}
class BioptimusValueError(BioptimusError, ValueError)
```

A [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror) that is also a `ValueError`.

Raised where the SDK historically raised a plain `ValueError` (for example an unsupported format or invalid input). Inheriting from both keeps existing `except ValueError` handlers working while exposing the typed [`code`](/sdk-reference/observability/errors#code), `context`, and `remediation`.

## BioptimusRuntimeError

```python theme={null}
class BioptimusRuntimeError(BioptimusError, RuntimeError)
```

A [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror) that is also a `RuntimeError`.

Raised where the SDK historically raised a plain `RuntimeError` (for example an unavailable backend or a failed operation). Inheriting from both keeps existing `except RuntimeError` handlers working while exposing the typed [`code`](/sdk-reference/observability/errors#code), `context`, and `remediation`.

## BioptimusImportError

```python theme={null}
class BioptimusImportError(BioptimusError, ImportError)
```

A [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror) that is also an `ImportError`.

Raised when a feature needs an optional dependency shipped as a `bioptimus-sdk` extra (for example `bioptimus-sdk[torch]`) that is not installed. Inheriting from both keeps existing `except ImportError` handlers working while exposing the typed [`code`](/sdk-reference/observability/errors#code), `context`, and `remediation` that name the missing extra and the exact install command.

***

#### wrap\_as

```python theme={null}
@contextmanager
def wrap_as(code: ErrorCode,
            *,
            message: str,
            error_cls: type[BioptimusError] = BioptimusRuntimeError,
            **context: Any) -> Iterator[None]
```

Translates an unexpected exception in the block into a typed error.

Centralizes the recurring "wrap a low-level failure as a typed error" boundary: an already-typed [`BioptimusError`](/sdk-reference/observability/errors#bioptimuserror) propagates unchanged, while any other exception is re-raised as `error_cls` with `code`, `message`, and `context` augmented with the original exception's type and detail. This mirrors `bioptimus.observability.fsboundary.fs_read`, but for arbitrary operations rather than filesystem reads.

<ParamField body="code">
  The [`ErrorCode`](/sdk-reference/observability/errors#errorcode) to tag the wrapped failure with.
</ParamField>

<ParamField body="message">
  The human-readable message for the wrapped error.
</ParamField>

<ParamField body="error_cls">
  The typed error class to raise. Defaults to [`BioptimusRuntimeError`](/sdk-reference/observability/errors#bioptimusruntimeerror); pass [`BioptimusValueError`](/sdk-reference/observability/errors#bioptimusvalueerror) for input-validation failures.
</ParamField>

<ParamField body="**context">
  Structured context fields recorded on the wrapped error, in addition to the automatically added `error_type` and `detail`.
</ParamField>

**Returns**:

A context manager that re-raises unexpected exceptions as `error_cls`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.