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



## Result Type [#result-type]

The SDK defines a type alias for all operations:

```rust
pub type Result<T> = std::result::Result<T, KubemqError>;
```

Use the `?` operator to propagate errors through `kubemq::Result<()>`.

## KubemqError [#kubemqerror]

The primary error type returned by all SDK operations. Each variant carries context including a machine-readable `ErrorCode`, human-readable message, and recovery suggestion.

| Variant          | Code             | Retryable | Description                                            |
| ---------------- | ---------------- | --------- | ------------------------------------------------------ |
| `Transient`      | `Transient`      | Yes       | Temporary failure (gRPC UNAVAILABLE, UNKNOWN, ABORTED) |
| `Timeout`        | `Timeout`        | Yes       | Operation timed out (gRPC DEADLINE\_EXCEEDED)          |
| `Throttling`     | `Throttling`     | Yes       | Rate limited (gRPC RESOURCE\_EXHAUSTED)                |
| `Authentication` | `Authentication` | No        | Invalid/expired auth token (gRPC UNAUTHENTICATED)      |
| `Authorization`  | `Authorization`  | No        | Insufficient permissions (gRPC PERMISSION\_DENIED)     |
| `Validation`     | `Validation`     | No        | Invalid request (empty channel, bad params)            |
| `NotFound`       | `NotFound`       | No        | Resource not found (gRPC NOT\_FOUND)                   |
| `Fatal`          | `Fatal`          | No        | Unrecoverable server error                             |
| `Cancellation`   | `Cancellation`   | No        | Operation cancelled                                    |
| `BufferFull`     | `Backpressure`   | No        | Internal send buffer full                              |
| `StreamBroken`   | `Transient`      | No        | Stream broken with unacknowledged messages             |
| `ClientClosed`   | `Fatal`          | No        | Client has been closed                                 |
| `Transport`      | `Fatal`          | No        | Low-level transport failure                            |
| `Handler`        | `Fatal`          | No        | User callback returned an error                        |

### Error Methods [#error-methods]

| Method           | Returns     | Description                                |
| ---------------- | ----------- | ------------------------------------------ |
| `is_retryable()` | `bool`      | Whether the operation may succeed on retry |
| `code()`         | `ErrorCode` | Machine-readable error classification      |
| `suggestion()`   | `&str`      | Human-readable recovery guidance           |

### Pattern Matching [#pattern-matching]

```rust title="main.rs"
use kubemq::{ErrorCode, KubemqError};

match err.code() {
    ErrorCode::Transient => println!("Retry with backoff"),
    ErrorCode::Timeout => println!("Increase timeout"),
    ErrorCode::Authentication => println!("Check auth token"),
    ErrorCode::Validation => println!("Fix: {}", err.suggestion()),
    _ => println!("Error: {}", err),
}
```

### Destructuring [#destructuring]

```rust title="main.rs"
match result {
    Err(KubemqError::Validation { code, message, suggestion, .. }) => {
        println!("Code: {:?}, Message: {}, Suggestion: {}", code, message, suggestion);
    }
    Err(KubemqError::Transient { is_retryable, request_id, .. }) => {
        println!("Retryable: {}, Request: {}", is_retryable, request_id);
    }
    _ => {}
}
```

## ErrorCode [#errorcode]

Machine-readable error classification enum.

| Variant          | gRPC Codes                                                               | Retryable |
| ---------------- | ------------------------------------------------------------------------ | --------- |
| `Transient`      | UNKNOWN, ABORTED, UNAVAILABLE                                            | Yes       |
| `Timeout`        | DEADLINE\_EXCEEDED                                                       | Yes       |
| `Throttling`     | RESOURCE\_EXHAUSTED                                                      | Yes       |
| `Authentication` | UNAUTHENTICATED                                                          | No        |
| `Authorization`  | PERMISSION\_DENIED                                                       | No        |
| `Validation`     | INVALID\_ARGUMENT, ALREADY\_EXISTS, FAILED\_PRECONDITION, OUT\_OF\_RANGE | No        |
| `NotFound`       | NOT\_FOUND                                                               | No        |
| `Fatal`          | UNIMPLEMENTED, INTERNAL, DATA\_LOSS                                      | No        |
| `Cancellation`   | CANCELLED                                                                | No        |
| `Backpressure`   | N/A (internal buffer full)                                               | No        |

## Subscription [#subscription]

Handle returned by `subscribe_to_*` methods. Use it to cancel an active subscription.

| Method          | Description                                  |
| --------------- | -------------------------------------------- |
| `unsubscribe()` | Cancel the subscription and wait for cleanup |
| `done()`        | Wait until the subscription task completes   |

## AsyncCallback [#asynccallback]

Type alias for subscription message handlers:

```rust
pub type AsyncCallback<T> =
    Box<dyn Fn(T) -> Pin<Box<dyn Future<Output = ()> + Send>> + Send + Sync>;
```

Used with `Box::pin(async move { ... })` in subscription callbacks.