> ## Documentation Index
> Fetch the complete documentation index at: https://docs.radion.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The Radion SDK error hierarchy and server error codes.

The SDK groups its errors in a small tree. TypeScript and Python use the same set of classes. Rust uses one `RadionError` enum with matching variants.

| Type / variant                                      | Raised when                                                                      |
| --------------------------------------------------- | -------------------------------------------------------------------------------- |
| `RadionError`                                       | The base class for every SDK error (the enum itself in Rust).                    |
| `RadionConnectionError` / `RadionError::Connection` | You used the client in a bad state (for example, no key, or used after `close`). |
| `RadionServerError` / `RadionError::Server`         | The server sent an `error` frame. Holds `code`, `channel`, and `id`.             |
| `RadionError::Transport` (Rust)                     | The WebSocket transport under the hood failed.                                   |

The SDK does not throw server errors or handler errors from a method. It sends them to the `error` lifecycle event instead.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { RadionConnectionError, RadionServerError } from "@radion-app/sdk";

  radion.realtime.onLifecycle("error", (err) => {
    if (err instanceof RadionServerError) {
      console.error("server error", err.code, err.channel, err.id);
    } else if (err instanceof RadionConnectionError) {
      console.error("connection error", err.message);
    }
  });
  ```

  ```python Python theme={null}
  from radion import RadionConnectionError, RadionServerError

  @radion.realtime.on_lifecycle("error")
  async def errored(err):
      if isinstance(err, RadionServerError):
          print("server error", err.code, err.channel, err.id)
      elif isinstance(err, RadionConnectionError):
          print("connection error", err)
  ```

  ```rust Rust theme={null}
  use futures_util::StreamExt;
  use radion_sdk::realtime::LifecycleEvent;
  use radion_sdk::RadionError;

  let mut lifecycle = radion.realtime.lifecycle();
  while let Some(event) = lifecycle.next().await {
      if let LifecycleEvent::Error(err) = event {
          match err {
              RadionError::Server { code, channel, id, .. } => {
                  eprintln!("server error {code:?} {channel:?} {id:?}");
              }
              RadionError::Connection(message) => eprintln!("connection error {message}"),
              RadionError::Transport(message) => eprintln!("transport error {message}"),
              _ => {}
          }
      }
  }
  ```
</CodeGroup>

## Server error codes

`RadionServerError.code` matches the server's [error frames](/websockets/frames#error-frames). Common codes:

| Code                  | Meaning                                                                      |
| --------------------- | ---------------------------------------------------------------------------- |
| `unknown_channel`     | The channel name is unknown, or a required filter is missing.                |
| `subscription_limit`  | You went over your plan's subscription limit for the connection.             |
| `lagged`              | You read too slowly and fell behind the buffer, so some events were dropped. |
| `key_revoked`         | The API key was revoked, so the connection is closed.                        |
| `revalidation_failed` | The key could not be checked again, so the connection is closed.             |

Treat `key_revoked` and `revalidation_failed` as fatal: call `close()` and stop. For normal drops, the client reconnects on its own.