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



## Error Hierarchy [#error-hierarchy]

All SDK errors inherit from `KubeMQ::Error`, which extends `StandardError`. Each error carries structured context for targeted recovery.

```text
KubeMQ::Error
├── KubeMQ::ConnectionError
│   └── KubeMQ::AuthenticationError
├── KubeMQ::TimeoutError
├── KubeMQ::ValidationError
├── KubeMQ::ConfigurationError
├── KubeMQ::ChannelError
├── KubeMQ::MessageError
├── KubeMQ::TransactionError
├── KubeMQ::ClientClosedError
├── KubeMQ::ConnectionNotReadyError
├── KubeMQ::StreamBrokenError
├── KubeMQ::BufferFullError
└── KubeMQ::CancellationError
```

## KubeMQ::Error [#kubemqerror]

Base exception class with structured context.

| Attribute    | Type        | Description                                  |
| ------------ | ----------- | -------------------------------------------- |
| `code`       | `String`    | SDK error code                               |
| `details`    | `Hash`      | Additional error context                     |
| `operation`  | `String`    | The operation that failed                    |
| `channel`    | `String`    | Channel name involved                        |
| `request_id` | `String`    | Request ID for correlation                   |
| `suggestion` | `String`    | Actionable suggestion for resolution         |
| `retryable?` | `Boolean`   | Whether the operation may succeed on retry   |
| `cause`      | `Exception` | Original exception that triggered this error |

```ruby
begin
  client.send_event(msg)
rescue KubeMQ::TimeoutError => e
  retry if e.retryable?
rescue KubeMQ::ValidationError => e
  puts "#{e.message} — #{e.suggestion}"
rescue KubeMQ::Error => e
  puts "#{e.class}: #{e.message} (code=#{e.code})"
end
```

## Error Types [#error-types]

| Error Class               | Retryable | Description                                 |
| ------------------------- | --------- | ------------------------------------------- |
| `ConnectionError`         | Varies    | gRPC connection failed or lost              |
| `AuthenticationError`     | No        | Invalid or expired auth token               |
| `TimeoutError`            | Yes       | Operation exceeded deadline                 |
| `ValidationError`         | No        | Invalid request parameters                  |
| `ConfigurationError`      | No        | Invalid client configuration                |
| `ChannelError`            | Varies    | Channel operation failed at broker          |
| `MessageError`            | Varies    | Message send/receive failed                 |
| `TransactionError`        | Varies    | Queue ack/nack/requeue failed               |
| `ClientClosedError`       | No        | Operation on a closed client                |
| `ConnectionNotReadyError` | No        | Transport not yet connected                 |
| `StreamBrokenError`       | Yes       | gRPC bidirectional stream broke             |
| `BufferFullError`         | No        | Reconnect message buffer at capacity        |
| `CancellationError`       | No        | Operation cancelled via `CancellationToken` |

## CancellationToken [#cancellationtoken]

Cooperative cancellation for subscriptions and long-running operations.

```ruby
token = KubeMQ::CancellationToken.new

client.subscribe_to_events(sub, cancellation_token: token) do |event|
  puts event.body
end

token.cancel
token.cancelled? # => true
```

| Method       | Description           |
| ------------ | --------------------- |
| `cancel`     | Signal cancellation   |
| `cancelled?` | Check if cancelled    |
| `wait`       | Block until cancelled |

## ServerInfo [#serverinfo]

Returned from `client.ping`.

| Attribute                | Type      | Description              |
| ------------------------ | --------- | ------------------------ |
| `host`                   | `String`  | Broker hostname          |
| `version`                | `String`  | Broker version           |
| `server_up_time_seconds` | `Integer` | Server uptime in seconds |

## ChannelInfo [#channelinfo]

Returned from `client.list_channels`.

| Attribute | Type      | Description                                |
| --------- | --------- | ------------------------------------------ |
| `name`    | `String`  | Channel name                               |
| `type`    | `String`  | Channel type                               |
| `active?` | `Boolean` | Whether the channel has active connections |

## Configuration Classes [#configuration-classes]

### TLSConfig [#tlsconfig]

```ruby
tls = KubeMQ::TLSConfig.new(
  enabled: true,
  cert_file: "/certs/client.pem",
  key_file: "/certs/client-key.pem",
  ca_file: "/certs/ca.pem",
  insecure_skip_verify: false
)
```

### KeepAliveConfig [#keepaliveconfig]

```ruby
keepalive = KubeMQ::KeepAliveConfig.new(
  enabled: true,
  ping_interval_seconds: 10,
  ping_timeout_seconds: 5,
  permit_without_calls: true
)
```

### ReconnectPolicy [#reconnectpolicy]

```ruby
policy = KubeMQ::ReconnectPolicy.new(
  enabled: true,
  base_interval: 1.0,
  multiplier: 2.0,
  max_delay: 30.0,
  jitter_percent: 0.25,
  max_attempts: 0
)
```

## ChannelType Constants [#channeltype-constants]

| Constant                            | Description           |
| ----------------------------------- | --------------------- |
| `KubeMQ::ChannelType::EVENTS`       | Events channels       |
| `KubeMQ::ChannelType::EVENTS_STORE` | Events store channels |
| `KubeMQ::ChannelType::QUEUES`       | Queue channels        |
| `KubeMQ::ChannelType::COMMANDS`     | Command channels      |
| `KubeMQ::ChannelType::QUERIES`      | Query channels        |