# Errors

> USearch for Mojo

Every fallible entry point raises `Error` and nothing else, since Mojo allows one error type per function.
An `Error` carries a `Status` shared with the C interface, so a fault this binding catches before the boundary reports the status the engine would have reported for the same fault:

```mojo
try:
    index.insert(keys, vectors)
except error:
    if error.status == Status.SHAPE_MISMATCH:
        pass  # the keys and the rows disagree
    print(error)  # USearch: shape-mismatch [usearch_dense_insert]
```

An `Error` keeps the engine mapped while it lives, since its name and message are the engine's own static text.
`library.status_name` and `status_from_name` spell and parse a `Status` through the engine's own name table, as their twins do for scalars, residencies, traversals, moods and dense metrics:

```mojo
print(library.status_name(Status.READ_ONLY), library.scalar_name(ScalarKind.BF16))  # read-only bf16
```

`from usearch import Status, Error`

## Status

Why a call into the engine failed - the `usearch_status_t` vocabulary, verbatim.

```mojo
struct Status
```

An [`Error`](#Error) never carries [`SUCCESS`](#SUCCESS) or [`DEFERRED`](#DEFERRED): only a [`Deferred`](https://www.unum.cloud/docs/usearch/mojo/executors.md#Deferred) reports the latter, and only
until its call is final. [`Library.status_name`](https://www.unum.cloud/docs/usearch/mojo/introspection.md#status_name) spells each one as the engine does.

- `SUCCESS` = `Status(Int32(0))`: The call completed.
- `DEFERRED` = `Status(Int32(1))`: The call was submitted deferred and is not final yet; the one non-final status.
- `OUT_OF_MEMORY` = `Status(Int32(2))`: An allocation or reservation could not be satisfied.
- `SHAPE_MISMATCH` = `Status(Int32(3))`: Dimensionality or row counts disagree.
- `UNSUPPORTED_LAYOUT` = `Status(Int32(4))`: A stride or packing the engine cannot traverse.
- `UNKNOWN_KIND` = `Status(Int32(5))`: A scalar, metric, or residency tag this build does not know.
- `READ_ONLY` = `Status(Int32(6))`: A mutating verb on a handle that serves its checkpoint in place.
- `IO` = `Status(Int32(7))`: A file could not be opened, read, written, or parsed.
- `DEVICE` = `Status(Int32(8))`: A device could not be selected, or its memory could not be claimed.
- `MALFORMED` = `Status(Int32(9))`: A caller-supplied representation could not be decoded.
- `INTERNAL` = `Status(Int32(10))`: The engine reported neither success nor a failure, which names a defect rather than a state.
- `OVERFLOW` = `Status(Int32(11))`: A hard design ceiling was reached, so a smaller request cannot help.
- `UNINITIALIZED` = `Status(Int32(12))`: The verb needs a prior successful reservation that never happened.
- `CONFIG_MISMATCH` = `Status(Int32(13))`: The request contradicts an already-frozen configuration.
- `CONTENDED` = `Status(Int32(14))`: The call was refused rather than waited for, like a submission to a full deferred table.
- `CANCELLED` = `Status(Int32(15))`: A progress handler stopped the operation; it published nothing.
- `UNSUPPORTED` = `Status(Int32(16))`: The verb is declared for every residency but this one does not implement it.
- `INVALID_ARGUMENT` = `Status(Int32(17))`: An argument breaks the verb's contract, like a required output left null.
- `LIBRARY_MISSING` = `Status(Int32(-1))`: Nothing to `dlopen` - the binding's own.
- `SYMBOL_MISSING` = `Status(Int32(-2))`: The library loaded but does not export a symbol the binding needs - the binding's own.
- `VERSION_MISMATCH` = `Status(Int32(-3))`: The library loaded but reports a different major version than the binding's - the binding's own.
- `code` `Int32`: The raw `usearch_status_t` value, kept even when this build does not name it.

Conforms to: `Copyable`, `Deinitable`, `Equatable`, `ImplicitlyCopyable`, `Movable`, `RegisterPassable`, `TrivialRegisterPassable`

## of

Lifts a raw `usearch_status_t`, keeping an unnamed one rather than guessing.

```mojo
def of(code: Int32) -> Self
```

- `code`: Whatever the C call reported, named by this build or not.

## Error

What went wrong inside the engine, and which entry point it was about.

```mojo
struct Error
```

- `status` `Status`: Which class of failure the engine reported.
- `detail` `StaticString`: The entry point it was about, for a reader rather than for a branch.
- `message` `Address`: The engine's own static message, or `NULL_ADDRESS` when it carried none.
- `name` `Address`: The engine's spelling of [`status`](https://www.unum.cloud/docs/usearch/mojo/executors.md#status) from `usearch_status_name`, or `NULL_ADDRESS` where no engine named it.
- `library` `Optional[Library]`: The engine `message` and `name` live in, kept mapped for as long as the error is; Mojo would otherwise unload it at the last handle's last use, while the error is still being read.

Conforms to: `Copyable`, `Deinitable`, `ImplicitlyCopyable`, `Movable`, `Writable`

## __init__

A failure the binding caught before any engine could name it.

```mojo
def __init__(out self, status: Status, detail: StringSpan[ImmStaticOrigin])
```

- `status`: Which class of failure it is.
- `detail`: The entry point or binding type it was about.

## write_to

Writes the status name, the entry point, and the engine's own message together.

```mojo
def write_to(self, mut writer: T)
```

- `writer` (mut): The sink the message is appended to.