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

# Error Handling

> Handle SDK errors and show player-friendly messages.

Most failed HyperX API calls throw `HyperXServerException`. Startup failures are separated into `HyperXInitializationException`.

## Basic Pattern

```cs theme={null}
try
{
    var meta = await HyperX.Core.PublicStorage.GetMeta("config/liveops.json");
    Debug.Log($"Hash: {meta.Hash}");
}
catch (HyperX.HyperXServerException ex)
{
    Debug.LogWarning($"HyperX error: {ex.ErrorCode}");
    Debug.LogWarning($"TraceId: {ex.TraceId}, RequestId: {ex.RequestId}");

    if (ex.ErrorCode == "STORAGE_OBJECT_NOT_FOUND")
    {
        // Use a default config or ask an operator to upload the file.
    }
}
```

## Useful Fields

| Field           | Use                                                    |
| --------------- | ------------------------------------------------------ |
| `ErrorCode`     | Stable code for branching in game logic.               |
| `ServerMessage` | Human-readable server message.                         |
| `StatusCode`    | HTTP status code.                                      |
| `TraceId`       | ID used to connect the request to server logs.         |
| `RequestId`     | ID for one request.                                    |
| `Context`       | Extra values such as filename, table key, or provider. |

Show game-specific messages to players instead of raw server messages. Keep `TraceId` and `RequestId` in support logs.

## Common Cases

| Situation            | Example Code               | Recommended Handling                                        |
| -------------------- | -------------------------- | ----------------------------------------------------------- |
| Login required       | `UNAUTHORIZED`             | Refresh the session, then return to login if refresh fails. |
| Missing file         | `STORAGE_OBJECT_NOT_FOUND` | Use a default asset or check Console upload state.          |
| Invalid data         | `VALIDATION_ERROR`         | Match the JSON payload to the Console schema.               |
| Invalid social token | `INVALID_PROVIDER_TOKEN`   | Get a fresh token from the provider SDK and retry login.    |
| Muted chat sender    | `CHAT_SENDER_MUTED`        | Disable chat input and show a muted-state message.          |

## Download Errors

`PublicStorage.Get(...)` returns a progress object first. Handle the actual failure when awaiting `progress.File`.

```cs theme={null}
var progress = HyperX.Core.PublicStorage.Get("patch/main.bundle", "patch/main.bundle");

try
{
    await progress.File;
}
catch (HyperX.HyperXServerException ex)
{
    Debug.LogWarning($"Download failed: {ex.ErrorCode}");
}
```