The C++ SDK uses explicit Status and StatusOr<T> return types instead of exceptions. All public API methods return these types, requiring callers to check ok() before accessing values.

Status

Represents the result of an operation (success or error).

kubemq::Status status = client->SendEvent(event);
if (!status.ok()) {
    std::cerr << "Code: " << static_cast<int>(status.code())
              << " Message: " << status.message()
              << " Retryable: " << status.is_retryable() << "\n";
}

Method	Return Type	Description
`ok()`	`bool`	True if operation succeeded
`code()`	`ErrorCode`	Error code (`kOk` if successful)
`message()`	`const string&`	Human-readable error description
`is_retryable()`	`bool`	Whether the error is transient
`operation()`	`const string&`	Operation that failed
`channel()`	`const string&`	Channel associated with error
`request_id()`	`const string&`	Request ID associated with error
`ToString()`	`string`	Formatted string representation

Sentinel Errors

Constant	Description
`kErrClientClosed`	Client has been closed
`kErrNotImplemented`	Operation is not implemented
`kErrValidation`	Input validation failed

StatusOr<T>

Holds either a value of type T (success) or a Status (error). Use ok() to check state, then value() or operator* to access the value.

auto result = client->Ping();
if (result.ok()) {
    std::cout << "Host: " << result->host << "\n";
} else {
    std::cerr << "Error: " << result.status().message() << "\n";
}

Method	Description
`ok()`	True if holding a value
`value()`	Access value (throws `BadStatusAccess` if error)
`operator*()`	Dereference value (undefined behavior if error)
`operator->()`	Access value via pointer
`status()`	Get the error Status (OK if holding a value)
`operator bool()`	Same as `ok()`

BadStatusAccess

Exception thrown by StatusOr::value() when the StatusOr holds an error. Callers should check ok() before calling value().

ErrorCode

Code	Description
`kOk`	Success
`kTransient`	Retryable network error (maps to gRPC UNAVAILABLE)
`kTimeout`	Operation timed out
`kThrottling`	Rate-limited (maps to gRPC RESOURCE_EXHAUSTED)
`kAuthentication`	Authentication failed
`kAuthorization`	Authorization denied
`kValidation`	Input validation failed
`kNotFound`	Resource not found
`kFatal`	Unrecoverable server error (maps to gRPC INTERNAL)
`kCancellation`	Context cancelled (maps to gRPC CANCELLED)
`kBackpressure`	Buffer full — backpressure applied

Domain Error Types

BufferFullError

Indicates the reconnect buffer is full and messages were discarded.

Method	Description
`buffer_size()`	Buffer capacity
`queued_count()`	Messages that were queued

StreamBrokenError

Indicates a stream was broken with unacknowledged messages.

Method	Description
`unacknowledged_ids()`	Vector of unacked message IDs

TransportError

Wraps a transport-level (gRPC) failure.

Method	Description
`operation()`	The operation that failed
`cause()`	The underlying Status error

HandlerError

Indicates a subscription callback handler failed.

Method	Description
`handler()`	The handler name that failed
`cause()`	The underlying Status error

Constants

Channel Types

Constant	Value	Description
`kChannelTypeEvents`	`"events"`	Fire-and-forget events
`kChannelTypeEventsStore`	`"events_store"`	Persistent events
`kChannelTypeCommands`	`"commands"`	Synchronous commands
`kChannelTypeQueries`	`"queries"`	Synchronous queries
`kChannelTypeQueues`	`"queues"`	Guaranteed delivery queues

Default Timeouts

Constant	Value	Description
`kDefaultConnectionTimeout`	10s	Initial connection timeout
`kDefaultSendTimeout`	5s	Send operation timeout
`kDefaultRPCTimeout`	10s	Command/query timeout
`kDefaultQueuePollTimeout`	30s	Queue poll timeout
`kDefaultDrainTimeout`	5s	Drain timeout on close
`kDefaultKeepaliveTime`	10s	gRPC keepalive interval
`kDefaultKeepaliveTimeout`	20s	gRPC keepalive timeout
`kDefaultCallbackTimeout`	30s	Max callback duration

Size Limits

Constant	Value	Description
`kDefaultMaxReceiveMessageSize`	4 MB	Max inbound message
`kDefaultMaxSendMessageSize`	100 MB	Max outbound message
`kDefaultSubscriptionBufferSize`	10	Per-subscription buffer
`kDefaultMaxConcurrentCallbacks`	1	Max concurrent callbacks

Types & Errors