# Errors

> UCall for C

`#include <ucall/types.h>`

## ucall_status_t

Library-level outcomes, preserving USearch numbers for shared statuses.

```c
enum ucall_status_t
```

These codes represent library/transport-level outcomes. For HTTP-specific status codes (200, 404, 500), use `[ucall_http_status_t](https://www.unum.cloud/docs/ucall/c/requests.md#ucall_http_status_t)`.

Statuses fall into five categories. Resources: out of memory, I/O, and connections that failed or closed. Input: invalid arguments, malformed bytes, failed handshakes and rejected peers. State: uninitialized handles, unsupported features, names not found or already existing, overflow and contention. Interruptions: deferral, would-block and timeouts. Defects: internal failures. Any verb that allocates, binds a device or touches a file or a socket may also return a Resources status. A verb's own block lists only what its contract adds.

- `ucall_status_success_k` = `0`: The call succeeded; the outcome message is NULL.
- `ucall_status_deferred_k` = `1`: A submitted call has not finished; the only status that is never final.
- `ucall_status_out_of_memory_k` = `2`: An allocation or reservation could not be satisfied.
- `ucall_status_io_k` = `7`: A socket or file could not be opened, read, written, or closed.
- `ucall_status_malformed_k` = `9`: The peer supplied bytes that cannot be decoded as the expected protocol.
- `ucall_status_internal_k` = `10`: The engine violated its contract, which points at a defect.
- `ucall_status_overflow_k` = `11`: The requested size exceeds the representable range.
- `ucall_status_uninitialized_k` = `12`: The call needs a handle that was never initialized.
- `ucall_status_contended_k` = `14`: The call was refused rather than waited for, such as submission to a full deferred table.
- `ucall_status_unsupported_k` = `16`: The build, backend, or machine does not implement the requested feature.
- `ucall_status_invalid_argument_k` = `17`: An argument is null, out of range, or contradicts another argument.
- `ucall_status_not_found_k` = `18`: The requested endpoint, header, or parameter does not exist.
- `ucall_status_already_exists_k` = `19`: An endpoint with the same template and method is already registered.
- `ucall_status_connection_failed_k` = `20`: DNS lookup or connection establishment failed.
- `ucall_status_connection_closed_k` = `21`: The connection closed before the exchange completed.
- `ucall_status_timeout_k` = `22`: The operation exceeded its time budget.
- `ucall_status_handshake_failed_k` = `23`: The Noise handshake failed to authenticate or agree on keys.
- `ucall_status_peer_rejected_k` = `24`: The peer authorizer declined the authenticated static key.
- `ucall_status_would_block_k` = `25`: A nonblocking poll had no progress to report.

Spellings: ```
char const * ucall_status_name(ucall_status_t status);
```

```
ucall_status_t ucall_status_from_name(ucall_bytes_view_t name);
```

## ucall_outcome_t

Outcome of one call: a status to branch on, and a static message with the detail it cannot carry.

```c
struct ucall_outcome_t
```

The message has static storage, is never freed, and is `NULL` exactly when the status is [`ucall_status_success_k`](#ucall_status_success_k). Every verb struct points at one.

- `status` `ucall_status_t`: The final status, or ucall_status_deferred_k while a submitted call is unfinished.
- `message` `char const *`: Static detail, never freed; NULL exactly on success.

## ucall_outcome_wait

Blocks until `outcome` is final, waiting on its status word through the CPU class's waiter, and with acquire ordering.

```c
ucall_status_t ucall_outcome_wait(ucall_outcome_t *outcome);
```

Producers publish the final status with a release store on that word, which the waiter watches. Never wait from a callback that the call itself must finish before it can complete.

- `outcome` (in): An outcome passed to a call, read until its status leaves [`ucall_status_deferred_k`](#ucall_status_deferred_k).

Notes: __Thread-safe__. Any number of threads may wait on one outcome.

## ucall_outcome_status

Reads the outcome without waiting, with acquire ordering, so a final status publishes every output.

```c
ucall_status_t ucall_outcome_status(ucall_outcome_t *outcome);
```

Poll through this function; directly reading the field during a deferred call is not an atomic load.

- `outcome` (in): An outcome passed to a call.

Statuses: - [`ucall_status_deferred_k`](#ucall_status_deferred_k) The call is not final.