Status and exception reference

Most Clustron Zaris operations report their outcome as a status on the result they return, rather than by throwing. This reference lists every status value, what it means, and whether the client retries it for you — followed by the exception types you may still encounter.

How operations report outcomes

Data operations return a KvResult (or KvResult<T> when they carry a value). You inspect the result instead of catching an exception:

var result = await client.GetAsync<string>("user:42");

if (result.IsSuccess)
{
    Use(result.Value);
}
else if (result.Status == KvStatus.NotFound)
{
    // Expected absence — not an error condition.
}
else
{
    Log(result.Status, result.Error);
}

• IsSuccess — true when the operation succeeded.
• Value — the returned value, on a successful KvResult<T>.
• Status — a KvStatus describing the outcome (see below).
• Error — a human-readable message when the operation did not succeed.

Status reference

The "Client retries" column indicates whether the built-in client retry loop retries the status automatically before returning it to you. Statuses marked auto are retried (with backoff, and a routing refresh where relevant); the rest are returned directly so your code can decide what to do.

Success and absence

Status	Meaning	Client retries
Success	The operation completed successfully.	—
NotFound	The key does not exist, or it expired. This is a normal answer to a read, not a failure.	No

Invalid request

These mean the request itself needs to change; retrying it unchanged will fail the same way.

Status	Meaning	Client retries
InvalidInput / InvalidArgument	The request was malformed — for example a missing key or an invalid option. (InvalidArgument is an alias of InvalidInput.)	No
InvalidQuery	A scan or query expression was invalid.	No

Concurrency and locking

Status	Meaning	Client retries
Conflict	An optimistic-concurrency check failed — the data changed under you (for example in a transaction). Re-read and reapply.	No
Locked	The key or resource is held by a lock. Back off and retry, or acquire the lock yourself.	No

Routing and ownership

These mean "you reached the wrong node for this key." The client refreshes its routing view and retries automatically, so you rarely observe them.

Status	Meaning	Client retries
Moved	The node does not own the key's partition — routing is stale.	Auto
ReplicaWriteRejected	The node owns the partition but is a replica, not the active primary; writes go to the primary.	Auto
OwnershipChanging	The partition's active ownership is mid-transition (for example a failback handoff). Distinct from Moved — the ownership is changing right now.	Auto

Availability

Status	Meaning	Client retries
Unavailable	The partition or node cannot serve right now — for example it is not yet ready or has no active owner.	Auto
Migrating	The partition is mid-migration. The client retries with extended backoff.	Auto
Timeout	The operation did not complete within its deadline. Safe to retry for idempotent operations.	No
TransportError	A network or transport-level failure occurred.	No
Cancelled	The operation was cancelled (for example via a cancellation token).	No

Replication

Status	Meaning	Client retries
ReplicationQuorumNotReached	A synchronous write did not reach the required number of replicas within the ack timeout.	No
ReplicaSyncPending	A replica read found data not yet synchronized from the primary. Retry, or read from the primary.	No

Capacity

See Memory and eviction for the model behind these.

Status	Meaning	Client retries
CapacityExceeded	The active owner is at its memory ceiling and eviction is disabled, so the write was rejected. Applies only to no-eviction mode, which is not selectable in the current release, so it is not normally encountered.	No
ItemTooLarge	The single item exceeds the configured maximum item size (4 MiB by default).	No

Security

Status	Meaning	Client retries
Unauthorized	Token security is enabled and the presented token was missing, invalid, expired, or not authorized for this store. Verified once per connection at the handshake.	No

General

Status	Meaning	Client retries
Error	An unclassified server-side error. Consult Error for detail.	No

Exceptions

Some conditions surface as exceptions rather than statuses — chiefly transport and ownership failures that occur below the result layer. The built-in retry loop treats the following as transient and retries them before giving up:

Exception	Meaning
TransportException	A transport-level failure talking to a node.
SocketException	A lower-level socket failure.
PartitionUnavailableException	The partition could not be served.
NodeUnavailableException	The target node was unreachable.
TimeoutException	An operation exceeded its deadline at the transport layer.

Other exceptions you may catch include ConcurrencyException (a concurrency violation surfaced as a throw) and LockingException (a lock operation failure). When retries are exhausted, the client returns the final result — a retryable status such as Unavailable as the final KvResult, or a TransportException for transport-level failures.

Next steps

• Client resilience patterns — how to retry, time out, and fail over correctly
• Handle errors
• Configuration reference