.NET SDK Error Handling

​

Overview

• When a HyperX Core API request fails, the SDK throws HyperXServerException.
• This lets the game client detect server failures and show a proper message to the player.

​

Exception fields

• ErrorCode: The server error code.
• Service: The internal service identifier where the error happened.
• ServerMessage: A human-readable error message from the server.
• StatusCode: The HTTP status code.
• TraceId: A trace identifier you can correlate with server logs.
• RequestId: A request-scoped identifier.
• Context: Additional context values useful for debugging.
• ResponseBody: The raw response body returned by the server.
• Even when the server response does not include a code field yet, the SDK generates a fallback code such as STORAGE_OBJECT_NOT_FOUND.
• When the server includes service, traceId, requestId, or context in the response body, the SDK parses them into structured fields.
• If the body does not include tracing metadata, the SDK falls back to x-service, x-trace-id, and x-request-id response headers.

​

Basic example

try
{
    var meta = await HyperX.Core.PublicStorage.GetMeta("missing-file.png");
}
catch (HyperX.HyperXServerException ex)
{
    Debug.Log($"ErrorCode: {ex.ErrorCode}");
    Debug.Log($"Service: {ex.Service}");
    Debug.Log($"Message: {ex.ServerMessage}");
    Debug.Log($"HTTP Status: {(int)ex.StatusCode}");
    Debug.Log($"TraceId: {ex.TraceId}");

    if (ex.Context.ContainsKey("path"))
    {
        Debug.Log($"Path: {ex.Context["path"]}");
    }
}

​

Handling patterns

• APIs that are awaited directly, such as GetMeta, GetHash, and Core.GetTime, can be handled with a normal try/catch.
• PublicStorage.Get(...) returns FileDownloadProgress immediately, so download failures should be handled at await progress.File.

var progress = HyperX.Core.PublicStorage.Get("missing-file.png");

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