# Errors

> USearch for C

The library never logs or aborts: every failure is a status in the call's `usearch_outcome_t`, with a static message carrying the detail the status cannot.
Messages are never freed, and are `NULL` exactly on success.
`usearch_status_name` spells a status as its lowercase dashed name, like `invalid-argument`, and `usearch_status_from_name` reads one back.
The statuses worth branching on:

- `usearch_status_unsupported_k`: the verb is declared but this residency or build does not implement it, so no retry can help.
- `usearch_status_read_only_k`: a mutating verb on a viewed handle.
- `usearch_status_contended_k`: refused rather than waited for, like an executor or an arena serving another call, an insertion meeting a refinement, absorption or clear of its index, or a second VRAM insertion beside the first.
- `usearch_status_cancelled_k`: a progress handler stopped the call, which published nothing.
- `usearch_status_device_k`: an executor, arena or handle on another residency or device than the call needs, or a GPU arena named with another executor than the one that made it.
- `usearch_status_invalid_argument_k`: a required pointer left `NULL`, inputs inside the arena the call rewinds, a name no table spells.

The set describes the project's failures, not only this library's exits, so a binding validating before the call reports what the library would have.
We aim for no `NULL` that switches behaviour, no bitmask that mixes unrelated options, and no field that repeats what another already says.

`#include <usearch/types.h>`

## usearch_status_t

What went wrong, in a vocabulary shared by the engine and by every binding that validates before calling it - so one failure carries one identity, whoever catches it.

```c
enum usearch_status_t
```

Some enumerators name failures this library never returns itself: a binding holding richer layout information than the ABI can accept rejects the call before it crosses, and reports the same status the engine would if it could see the same thing. The set describes the project's failures, not this implementation's exits, so unused enumerators are deliberate.

The failures fall into five categories. Resources: [`usearch_status_out_of_memory_k`](#usearch_status_out_of_memory_k), [`usearch_status_device_k`](#usearch_status_device_k) and [`usearch_status_io_k`](#usearch_status_io_k). Input: [`usearch_status_shape_mismatch_k`](#usearch_status_shape_mismatch_k), [`usearch_status_unsupported_layout_k`](#usearch_status_unsupported_layout_k), [`usearch_status_unknown_kind_k`](#usearch_status_unknown_kind_k), [`usearch_status_malformed_k`](#usearch_status_malformed_k) and [`usearch_status_invalid_argument_k`](#usearch_status_invalid_argument_k). State: [`usearch_status_uninitialized_k`](#usearch_status_uninitialized_k), [`usearch_status_config_mismatch_k`](#usearch_status_config_mismatch_k), [`usearch_status_read_only_k`](#usearch_status_read_only_k), [`usearch_status_overflow_k`](#usearch_status_overflow_k), [`usearch_status_contended_k`](#usearch_status_contended_k) and [`usearch_status_unsupported_k`](#usearch_status_unsupported_k). Interruptions: [`usearch_status_cancelled_k`](#usearch_status_cancelled_k) and [`usearch_status_deferred_k`](#usearch_status_deferred_k). Defects: [`usearch_status_internal_k`](#usearch_status_internal_k). Any verb that allocates, binds a device or touches a file may also return a Resources status; any verb taking a progress callback may return [`usearch_status_cancelled_k`](#usearch_status_cancelled_k). A verb's own block lists only what its contract adds.

- `usearch_status_success_k` = `0`: The call succeeded; `message` carries nothing.
- `usearch_status_deferred_k` = `1`: The call was submitted deferred and is not final yet; the one non-final status.
- `usearch_status_out_of_memory_k` = `2`: An allocation or reservation could not be satisfied.
- `usearch_status_shape_mismatch_k` = `3`: Dimensionality or row counts disagree.
- `usearch_status_unsupported_layout_k` = `4`: A stride or packing the engine cannot traverse.
- `usearch_status_unknown_kind_k` = `5`: A scalar, metric, residency, traversal or relation tag this build does not know.
- `usearch_status_read_only_k` = `6`: A mutating verb on a handle that serves its checkpoint in place.
- `usearch_status_io_k` = `7`: A file could not be opened, read, written, or parsed.
- `usearch_status_device_k` = `8`: A device could not be selected, or its memory could not be claimed.
- `usearch_status_malformed_k` = `9`: A caller-supplied representation could not be decoded - a malformed key, a truncated buffer or checkpoint.
- `usearch_status_internal_k` = `10`: The library reported neither success nor a failure - a contract violation rather than a condition, so it names a defect and not a state.
- `usearch_status_overflow_k` = `11`: A hard design ceiling was reached, like the 32-bit ID space; a smaller request cannot help where a smaller allocation would.
- `usearch_status_uninitialized_k` = `12`: The verb needs a prior successful reservation that never happened.
- `usearch_status_config_mismatch_k` = `13`: The request contradicts an already-frozen configuration, like re-reserving with a different geometry.
- `usearch_status_contended_k` = `14`: The call was refused rather than waited for, like a submission to a full deferred table.
- `usearch_status_cancelled_k` = `15`: A progress handler asked the operation to stop; it unwound and published nothing, so the handle carries whatever it did before the call.
- `usearch_status_unsupported_k` = `16`: The verb is declared for every residency but this one does not implement it, its traversal or its predicate, or the build left the requested quantization out; no retry, option, or smaller request can help, so a caller picks another residency, traversal or build.
- `usearch_status_invalid_argument_k` = `17`: An argument breaks the verb's contract - a required pointer left `NULL`, inputs inside the arena the call rewinds, a name no table spells.

Spellings: ```
char const * usearch_status_name(usearch_status_t status);
```

```
usearch_status_t usearch_status_from_name(usearch_bytes_view_t name);
```

## usearch_outcome_t

Outcome of one call: a status every binding can branch on, and a static message carrying the detail the status cannot.

```c
struct usearch_outcome_t
```

Messages are static and __don't__ need to be deallocated, and are `NULL` exactly when the status is [`usearch_status_success_k`](#usearch_status_success_k).

- `status` `usearch_status_t`: What happened, for the caller to branch on.
- `message` `char const *`: The static detail behind a failing `status`, `NULL` on success.