# Errors

> USearch for Python

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

```python
try:
    index.on(pool).search(queries, 10, arena, progress=lambda completed, total: completed < 100)
except usearch.CancelledError:
    ...  # The handler stopped the call, which published nothing
except usearch.Error as error:
    print(error.status)  # Status.SHAPE_MISMATCH, Status.READ_ONLY, Status.DEVICE, ...
```

`usearch.Status` is an `enum.IntEnum` valued as `usearch_status_t`.
`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`
- `READ_ONLY` → `ReadOnlyError`
- `IO` → `InputOutputError`, an `OSError`
- `DEVICE` → `DeviceError`
- `MALFORMED` → `MalformedError`, a `ValueError`
- `INTERNAL` → `InternalError`
- `OVERFLOW` → `CapacityOverflowError`, an `OverflowError`
- `UNINITIALIZED` → `UninitializedError`
- `CONFIG_MISMATCH` → `ConfigMismatchError`, a `ValueError`
- `CONTENDED` → `ContendedError`
- `CANCELLED` → `CancelledError`
- `UNSUPPORTED` → `UnsupportedError`, a `NotImplementedError`
- `INVALID_ARGUMENT` → `InvalidArgumentError`, a `ValueError`

So `except ValueError` catches a `ShapeMismatchError`, `except OSError` an `InputOutputError`, and `except MemoryError` an `OutOfMemoryError`.
A failure the binding catches before the boundary raises the class the engine would have raised for the same fault.
Arguments the binding refuses raise at the call, while the engine's refusals of a deferred call raise at `await` or `wait()`, as many times as they are asked.

`import usearch`

`from usearch import Error`

## Status

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

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

- `SUCCESS` = `0`: The call succeeded.
- `DEFERRED` = `1`: The call was submitted deferred and is not final yet; the one non-final status.
- `OUT_OF_MEMORY` = `2`: An allocation or reservation could not be satisfied.
- `SHAPE_MISMATCH` = `3`: Dimensionality or row counts disagree.
- `UNSUPPORTED_LAYOUT` = `4`: A stride or packing the engine cannot traverse.
- `UNKNOWN_KIND` = `5`: A scalar, metric, residency, traversal or relation tag this build does not know.
- `READ_ONLY` = `6`: A mutating verb on a handle that serves its checkpoint in place.
- `IO` = `7`: A file could not be opened, read, written, or parsed.
- `DEVICE` = `8`: A device could not be selected, or its memory could not be claimed.
- `MALFORMED` = `9`: A caller-supplied key, buffer or checkpoint could not be decoded.
- `INTERNAL` = `10`: The library reported neither success nor a failure, which names a defect.
- `OVERFLOW` = `11`: A hard design ceiling was reached, like the 32-bit ID space; a smaller request cannot help.
- `UNINITIALIZED` = `12`: The verb needs a prior successful reservation that never happened.
- `CONFIG_MISMATCH` = `13`: The request contradicts an already-frozen configuration.
- `CONTENDED` = `14`: The call was refused rather than waited for, like a submission to a full deferred table.
- `CANCELLED` = `15`: A progress handler stopped the call, which published nothing.
- `UNSUPPORTED` = `16`: This residency, traversal or build does not implement the verb; no retry can help.
- `INVALID_ARGUMENT` = `17`: An argument breaks the verb's contract.

## OutOfMemoryError

An allocation or reservation could not be satisfied.

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

## ShapeMismatchError

Dimensionality or row counts disagree.

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

## UnsupportedLayoutError

A stride or packing the engine cannot traverse.

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

## UnknownKindError

A scalar, metric, or residency this build does not know.

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

## ReadOnlyError

A mutating verb on a handle that serves its checkpoint in place.

```python
class ReadOnlyError(Error)
```

## InputOutputError

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

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

## DeviceError

A device could not be selected, or its memory could not be claimed.

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

## MalformedError

A representation could not be decoded - a key, a buffer, a checkpoint.

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

## InternalError

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

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

## CapacityOverflowError

A hard design ceiling was reached; a smaller request cannot help.

```python
class CapacityOverflowError(Error, OverflowError)
```

## UninitializedError

The handle is not ready for the verb - absorbed as a donor, or closed.

```python
class UninitializedError(Error)
```

## ConfigMismatchError

The request contradicts an already-frozen configuration.

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

## ContendedError

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

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

## CancelledError

A progress handler stopped the call, which published nothing.

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

## UnsupportedError

This residency does not implement the verb; pick another residency.

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

## InvalidArgumentError

An argument breaks the verb's contract.

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

## Error

The base of every failure the library reports, one subclass per failing [`Status`](#Status).

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

## status

```python
status: Status
```