# Errors

> UForm for Python

Every failure raises a subclass of `uform.Error`, itself a `RuntimeError`, and each carries the status the C ABI reported as its `status` attribute, a `uform.Status` member:

```python
try:
    model.on(executor).text_encode(texts, arena, progress=lambda completed, total: completed < 100)
except uform.CancelledError:
    ...  # The handler stopped the call, which published nothing
except uform.Error as error:
    print(error.status)  # Status.SHAPE_MISMATCH, Status.DEVICE, ...
```

`SUCCESS` and `DEFERRED` raise nothing, and every other member has its own class, which also derives the built-in naming the same fault where one exists:

- `OUT_OF_MEMORY` → `OutOfMemoryError`, a `MemoryError`
- `SHAPE_MISMATCH` → `ShapeMismatchError`, a `ValueError`
- `UNSUPPORTED_LAYOUT` → `UnsupportedLayoutError`, a `ValueError`
- `UNKNOWN_KIND` → `UnknownKindError`, a `ValueError`
- `IO` → `InputOutputError`, an `OSError`
- `DEVICE` → `DeviceError`
- `MALFORMED` → `MalformedError`, a `ValueError`
- `INTERNAL` → `InternalError`
- `CONFIG_MISMATCH` → `ConfigMismatchError`, a `ValueError`
- `CONTENDED` → `ContendedError`
- `CANCELLED` → `CancelledError`
- `UNSUPPORTED` → `UnsupportedError`, a `NotImplementedError`
- `INVALID_ARGUMENT` → `InvalidArgumentError`, a `ValueError`

A failure the binding catches before the boundary raises the class the library would have raised for the same fault.
Arguments the binding refuses raise at the call, while the library's refusals of a deferred call raise at `await` or `wait()`.

`import uform`

`from uform import Error`

## Status

What a call finished with, valued as `uform_status_t`: [`Error.status`](#status) and [`Deferred.status`](#status).

```python
class Status(IntEnum)
```

- `SUCCESS` = `0`
- `DEFERRED` = `1`
- `OUT_OF_MEMORY` = `2`
- `SHAPE_MISMATCH` = `3`
- `UNSUPPORTED_LAYOUT` = `4`
- `UNKNOWN_KIND` = `5`
- `IO` = `7`
- `DEVICE` = `8`
- `MALFORMED` = `9`
- `INTERNAL` = `10`
- `CONFIG_MISMATCH` = `13`
- `CONTENDED` = `14`
- `CANCELLED` = `15`
- `UNSUPPORTED` = `16`
- `INVALID_ARGUMENT` = `17`

## OutOfMemoryError

Device, pinned, or host memory could not be allocated, or the scratch ceiling is too low.

```python
class OutOfMemoryError(Error, MemoryError)
```

## ShapeMismatchError

Item counts, a pixel shape, or a batch envelope disagree with the call or the model.

```python
class ShapeMismatchError(Error, ValueError)
```

## UnsupportedLayoutError

A stride or packing the model cannot read.

```python
class UnsupportedLayoutError(Error, ValueError)
```

## UnknownKindError

A scalar, modality, or name this build does not know.

```python
class UnknownKindError(Error, ValueError)
```

## InputOutputError

A checkpoint file could not be opened, read, or written.

```python
class InputOutputError(Error, OSError)
```

## DeviceError

The driver refused or the device faulted; after a fault the executor refuses every later call.

```python
class DeviceError(Error)
```

## MalformedError

Supplied bytes could not be decoded: a checkpoint, an image, a clip, or a recording.

```python
class MalformedError(Error, ValueError)
```

## InternalError

The library reported neither success nor a failure - a defect.

```python
class InternalError(Error)
```

## ConfigMismatchError

The request contradicts a frozen configuration, like resuming a checkpoint of another geometry.

```python
class ConfigMismatchError(Error, ValueError)
```

## ContendedError

An executor's deferred table or an arena is already serving another call.

```python
class ContendedError(Error)
```

## CancelledError

A progress handler stopped the call, which published nothing.

```python
class CancelledError(Error)
```

## UnsupportedError

The verb is declared, but this residency or model does not implement it.

```python
class UnsupportedError(Error, NotImplementedError)
```

## InvalidArgumentError

An argument breaks the verb's contract, a closed executor and a rewound arena's output included.

```python
class InvalidArgumentError(Error, ValueError)
```

## Error

The base of every failure the library reports, one subclass per status shared with the C API.

```python
class Error(RuntimeError)
```

## status

```python
status: Status
```