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



The Elixir SDK uses Elixir exceptions and structs for rich error handling and subscription lifecycle management.

## KubeMQ.Error [#kubemqerror]

An exception struct with structured error information. All failed SDK operations return `{:error, %KubeMQ.Error{}}`.

| Field        | Type         | Description                          |
| ------------ | ------------ | ------------------------------------ |
| `code`       | `atom()`     | Error category                       |
| `message`    | `String.t()` | Human-readable error description     |
| `operation`  | `String.t()` | The operation that failed            |
| `channel`    | `String.t()` | Channel involved (if applicable)     |
| `cause`      | `term()`     | Underlying error cause               |
| `retryable?` | `boolean()`  | Whether the operation can be retried |
| `request_id` | `String.t()` | Associated request ID                |

### Error Codes [#error-codes]

| Code              | Retryable | When                              |
| ----------------- | --------- | --------------------------------- |
| `:transient`      | Yes       | Temporary server or network issue |
| `:timeout`        | Yes       | Deadline exceeded                 |
| `:throttling`     | Yes       | Rate limit hit                    |
| `:authentication` | No        | Invalid credentials               |
| `:authorization`  | No        | Insufficient permissions          |
| `:validation`     | No        | Invalid parameters                |
| `:not_found`      | No        | Channel or resource not found     |
| `:fatal`          | No        | Unrecoverable server error        |

### Error Factories [#error-factories]

```elixir
KubeMQ.Error.transient("network timeout", operation: "connection.send_event")
KubeMQ.Error.timeout("deadline exceeded", operation: "client.send_command")
KubeMQ.Error.validation("channel is required", operation: "client.send_event")
KubeMQ.Error.authentication("invalid token", operation: "client.connect")
```

## KubeMQ.Subscription [#kubemqsubscription]

Manages an active subscription. Returned by all `subscribe_to_*` functions.

| Function    | Spec                              | Description             |
| ----------- | --------------------------------- | ----------------------- |
| `cancel/1`  | `(Subscription.t()) :: :ok`       | Cancel the subscription |
| `active?/1` | `(Subscription.t()) :: boolean()` | Check if still active   |

```elixir
{:ok, sub} = KubeMQ.Client.subscribe_to_events(client, "ch",
  on_event: fn e -> IO.puts(e.body) end)

KubeMQ.Subscription.active?(sub)  # true
KubeMQ.Subscription.cancel(sub)
KubeMQ.Subscription.active?(sub)  # false
```

## KubeMQ.ServerInfo [#kubemqserverinfo]

Returned by `KubeMQ.Client.ping/1`.

| Field                    | Type         | Description              |
| ------------------------ | ------------ | ------------------------ |
| `host`                   | `String.t()` | Server hostname          |
| `version`                | `String.t()` | Server version           |
| `server_start_time`      | `integer()`  | Server start timestamp   |
| `server_up_time_seconds` | `integer()`  | Server uptime in seconds |

## KubeMQ.ChannelInfo [#kubemqchannelinfo]

Returned by `KubeMQ.Client.list_channels/3`.

| Field           | Type         | Description                                 |
| --------------- | ------------ | ------------------------------------------- |
| `name`          | `String.t()` | Channel name                                |
| `type`          | `String.t()` | Channel type (e.g., `"events"`, `"queues"`) |
| `last_activity` | `integer()`  | Last activity timestamp                     |
| `is_active`     | `boolean()`  | Whether the channel is active               |
| `incoming`      | `integer()`  | Incoming message count                      |
| `outgoing`      | `integer()`  | Outgoing message count                      |

## Pattern Matching [#pattern-matching]

```elixir
case KubeMQ.Client.send_event(client, event) do
  :ok ->
    IO.puts("Sent!")

  {:error, %KubeMQ.Error{code: :timeout, retryable?: true}} ->
    IO.puts("Timed out — safe to retry")

  {:error, %KubeMQ.Error{code: :validation, message: msg}} ->
    IO.puts("Invalid input: #{msg}")

  {:error, %KubeMQ.Error{} = err} ->
    IO.puts("Error: #{Exception.message(err)}")
end
```

## See Also [#see-also]

* [Error Handling Examples](/sdks/elixir/how-to/error-handling/)
* [Elixir SDK Getting Started](/sdks/elixir)