# Types & Errors (/sdks/cpp/reference/types-and-errors)



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 [#status]

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

```cpp
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 [#sentinel-errors]

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

## StatusOr\<T> [#statusort]

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.

```cpp
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 [#badstatusaccess]

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

## ErrorCode [#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 [#domain-error-types]

### BufferFullError [#bufferfullerror]

Indicates the reconnect buffer is full and messages were discarded.

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

### StreamBrokenError [#streambrokenerror]

Indicates a stream was broken with unacknowledged messages.

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

### TransportError [#transporterror]

Wraps a transport-level (gRPC) failure.

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

### HandlerError [#handlererror]

Indicates a subscription callback handler failed.

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

## Constants [#constants]

### Channel Types [#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 [#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 [#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 |

## See Also [#see-also]

* [Error Handling Examples](/sdks/cpp/how-to/error-handling/)
* [C++ SDK Getting Started](/sdks/cpp)