Skip to main content

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.

​
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.
  • Core returns a structured error response together with x-service, x-trace-id, and x-request-id headers.

​
Exception fields

HyperXServerException includes the following 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.
  • The server code field is a stable machine-readable code that the SDK can branch on.
  • 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}");
    Debug.Log($"RequestId: {ex.RequestId}");

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

​
Missing storage file handling

When a Public Storage file does not exist, Core returns STORAGE_OBJECT_NOT_FOUND. In game clients, avoid showing the raw backend message to players. Handle it by using a default resource, retrying after content is published, or guiding the operator to upload the missing file. 
try
{
    var meta = await HyperX.Core.PublicStorage.GetMeta("config/liveops.json");
    Debug.Log($"Hash: {meta.Hash}");
}
catch (HyperX.HyperXServerException ex)
    when (ex.ErrorCode == "STORAGE_OBJECT_NOT_FOUND")
{
    Debug.LogWarning("LiveOps config is not published yet.");
    Debug.LogWarning($"TraceId: {ex.TraceId}, RequestId: {ex.RequestId}");

    // Example: use default config or ask an operator to upload the file.
}
When asking for support or checking server logs, include these values:
  • ErrorCode
  • Service
  • TraceId
  • RequestId
  • projectCode, key, filename, and operation from Context

​
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}");
}