# Errors

> USearch for Zig

Every verb answers `Error!T`, one error per final status of the C interface.
The engine checks every shape it can see; the binding checks only what never crosses the boundary, like a key run longer than its rows, and reports the status the engine would have.
The engine's static detail message rides an `Outcome` you lend: `diagnosed(&outcome)` on the index or a blocking receiver copies every call's final outcome into it, a constructor's config takes one as `diagnostics`, and a `Deferred` answers its own through `message`.
The binding's own refusals land there too, with a message of their own.
One set covers every verb rather than a narrower one per verb, since nothing in the ABI bounds which status a given call may report.

```zig
var outcome: usearch.Outcome = .{};
_ = index.on(executor).diagnosed(&outcome).search(queries, 10, &arena, .{}) catch |failure| {
    std.log.err("{s}: {s}", .{ @errorName(failure), outcome.text() });
    return failure;
};
var copy = try usearch.DenseIndex.loadRam("index.safegraphs", .{ .diagnostics = &outcome });
```

`Status`, `Scalar`, `Mood`, `Residency` and `DenseMetric` carry the C enumerators' values, and their `name` and `fromName` spell them through the C name tables, `fromName` answering null for text no table spells.

```zig
std.debug.print("{s}\n", .{usearch.Status.contended.name()}); // contended
const metric = usearch.DenseMetric.fromName("inner") orelse return error.UnknownMetric;
```

`const usearch = @import("usearch");`

`const Status = @import("usearch").Status;`

`const Outcome = @import("usearch").Outcome;`

## Error

One error per final failure status, so `@errorName` carries as much as the status itself does.

```zig
pub const Error = error
```

Zig error values hold no payload, so neither the static message nor the symbol that failed can
travel with the error. Lend an [`Outcome`](#Outcome) as a call's diagnostics, or read [`Deferred.message`](https://www.unum.cloud/docs/usearch/zig/executors.md#message),
where that detail matters.

One set serves every verb rather than a narrower one per verb: the engine answers each call
through the same [`Outcome`](#Outcome), and nothing in the ABI bounds which status a given verb may report,
so a narrower signature would be a promise this boundary cannot keep.

- `OutOfMemory`
- `ShapeMismatch`
- `UnsupportedLayout`
- `UnknownKind`
- `ReadOnly`
- `Io`
- `Device`
- `Malformed`
- `Internal`
- `Overflow`
- `Uninitialized`
- `ConfigMismatch`
- `Contended`
- `Cancelled`
- `Unsupported`
- `InvalidArgument`

## Status

What went wrong, mirroring `usearch_status_t` value-for-value.

```zig
pub const Status = enum(c_int)
```

Non-exhaustive, so a status a newer engine reports arrives intact rather than coerced.

- `success` = `0`: The call completed; the outcome's message carries nothing.
- `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, or residency 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 representation could not be decoded.
- `internal` = `10`: The library reported neither success nor a failure - a defect, not a state.
- `overflow` = `11`: A hard design ceiling was reached, like the 32-bit ID space.
- `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 - a full deferred table, or an arena serving another call.
- `cancelled` = `15`: A progress handler asked the operation to stop.
- `unsupported` = `16`: The verb is declared for every residency but this one does not implement it.
- `invalid_argument` = `17`: An argument breaks the verb's contract.

## name

The canonical spelling, "unrecognized" for a value no status carries.

```zig
pub fn name(self: Status) [:0]const u8
```

Calls `usearch_status_name`.

## fromName

Reads a spelling back, or null when no status spells it.

```zig
pub fn fromName(text: []const u8) ?Status
```

Calls `usearch_status_from_name`.

## Outcome

Outcome of one call: a status to branch on, and a static message carrying what the status cannot.

```zig
pub const Outcome = extern struct
```

Mirrors `usearch_outcome_t`, which every verb's argument structure points at.

Every verb answers `Error!T`, and a caller wanting the message too lends an [`Outcome`](#Outcome) as the
call's diagnostics, which the call's final outcome is copied into. Messages are static and need
no deallocation.

- `status` `Status`: What the call reported; `.success` is the only non-error.
- `message` `?[*:0]const u8`: Static, English detail, null exactly when the status is `.success`.

## check

Lifts the status into the error set; `.success` is the only non-error.

```zig
pub fn check(self: Outcome) Error!void
```

## text

The static detail the status could not carry; empty where the call reported none.

```zig
pub fn text(self: Outcome) [:0]const u8
```

## checkInto

Copies the outcome into `diagnostics` where one was lent, then lifts it as [`check`](#check) does.

```zig
pub fn checkInto(self: Outcome, diagnostics: ?*Outcome) Error!void
```