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

# Error handling

> How to integrate the Almedia SDK — synced from the source repository.

Subscribe to `OnErrorOccurred` to surface SDK failures:

```csharp theme={"theme":{"light":"github-light","dark":"night-owl"}}
Almedia.OnErrorOccurred += err =>
{
    Debug.LogError($"[Almedia] {err.Code}: {err.Message}");
};
```

Every error that reaches this event is one the game may want to know about, so routing it to `Debug.LogError` or a crash reporter is fine. Connectivity loss during work the SDK runs on its own - notification polling, event delivery, status refreshes, and a `FetchNotifications()` that finds no network - is logged at `Warning`, retried by the SDK, and never fires this event. A device that loses its signal after start-up produces no errors. Only `Initialize` still reports offline, because the game is waiting on its first status: `Disabled` when the configuration cannot be fetched, `NetworkFailure` when the status that follows it cannot.

| `AlmediaErrorCode` | Source | Typical meaning |
| - | - | - |
| `InvalidConfiguration` | Local or native | Missing integration key, malformed config. Fired synchronously from `Initialize` when keys are absent. |
| `NetworkFailure` | Native | A request the game asked for (`Initialize`, linking, opening a screen) did not reach the backend: offline, DNS, timeout, TLS. The same failure in the SDK's own background work is a `Warning` log, not an error. |
| `ServerError` | Native | The backend returned 5xx. |
| `RateLimited` | Native | The backend returned 429. Retry later. |
| `Disabled` | Native | Integration killswitch is on for this app. The SDK does not run until the backend re-enables it. |
| `LinkingFailed` | Native | The linking flow ended without success. The player can retry. |
| `InvalidState` | Native | A method was called in a state it does not support (for example, starting linking while already `Linked`). |
| `Unexpected` | Native | Catch-all for unhandled native exceptions. |
| `Unknown` | Native | The native side sent an error code the C# layer does not recognize; usually a version mismatch. |

Compare codes with `==`, for example `err.Code == AlmediaErrorCode.RateLimited`. Errors are non-fatal. The SDK keeps running and may recover on the next status update or fetch.

Do not retry `Initialize` directly from `OnErrorOccurred`. `Initialize` raises its own configuration errors before it returns, so the handler runs inside `Initialize`. The SDK ignores that retry and logs a `Warning`. Fix the configuration and retry from a later frame. The same configuration fails the same way.

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.