메인 콘텐츠로 건너뛰기

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.

​
개요

  • HyperX Core API 요청이 실패하면 SDK는 HyperXServerException을 발생시킵니다.
  • 이 예외를 사용하면 게임 클라이언트가 서버 오류를 감지하고, 유저에게 적절한 안내 메시지를 표시할 수 있습니다.
  • Core는 구조화된 오류 응답과 x-service, x-trace-id, x-request-id 헤더를 함께 반환합니다.

​
예외 정보

HyperXServerException에는 다음 정보가 포함됩니다.
  • ErrorCode: 서버 오류 코드입니다.
  • Service: 오류가 발생한 내부 서비스 식별자입니다.
  • ServerMessage: 서버가 전달한 사람이 읽을 수 있는 오류 메시지입니다.
  • StatusCode: HTTP 상태 코드입니다.
  • TraceId: 서버 로그와 연결할 수 있는 추적 ID입니다.
  • RequestId: 요청 단위 식별자입니다.
  • Context: 디버깅에 필요한 추가 컨텍스트 정보입니다.
  • ResponseBody: 서버가 반환한 원본 응답 본문입니다.
  • 서버 응답의 code 필드는 SDK가 안정적으로 분기할 수 있는 머신용 코드입니다.
  • 서버가 service, traceId, requestId, context를 응답 본문에 포함하면 SDK가 구조화된 필드로 파싱합니다.
  • 본문에 추적 정보가 없더라도 x-service, x-trace-id, x-request-id 헤더가 있으면 fallback으로 채웁니다.

​
기본 사용 예시

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

​
스토리지 파일 누락 처리

존재하지 않는 Public Storage 파일을 조회하면 Core는 STORAGE_OBJECT_NOT_FOUND를 반환합니다. 게임 클라이언트에서는 이 오류를 사용자에게 그대로 노출하기보다, 필요한 파일을 다시 내려받거나 기본 리소스로 대체하는 식으로 처리하세요. 
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}");

    // 예: 기본 설정을 사용하거나, 운영자가 파일을 업로드하도록 안내합니다.
}
지원 요청이나 운영 로그 확인이 필요하면 다음 값을 함께 전달하세요.
  • ErrorCode
  • Service
  • TraceId
  • RequestId
  • Context의 projectCode, key, filename, operation

​
처리 패턴

  • GetMeta, GetHash, Core.GetTime처럼 await하는 API는 일반적인 try/catch로 처리할 수 있습니다.
  • PublicStorage.Get(...)은 즉시 FileDownloadProgress를 반환하므로, 다운로드 실패는 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}");
}