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

KubeMQ.Error

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

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

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

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

{: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

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

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

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

Types & Errors