.NET SDK 에러 처리

​

개요

• HyperX Core API 요청이 실패하면 SDK는 HyperXServerException을 발생시킵니다.
• 이 예외를 사용하면 게임 클라이언트가 서버 오류를 감지하고, 유저에게 적절한 안내 메시지를 표시할 수 있습니다.

​

예외 정보

• ErrorCode: 서버 오류 코드입니다.
• Service: 오류가 발생한 내부 서비스 식별자입니다.
• ServerMessage: 서버가 전달한 사람이 읽을 수 있는 오류 메시지입니다.
• StatusCode: HTTP 상태 코드입니다.
• TraceId: 서버 로그와 연결할 수 있는 추적 ID입니다.
• RequestId: 요청 단위 식별자입니다.
• Context: 디버깅에 필요한 추가 컨텍스트 정보입니다.
• ResponseBody: 서버가 반환한 원본 응답 본문입니다.
• 현재 서버 응답에 code 필드가 없더라도, SDK가 STORAGE_OBJECT_NOT_FOUND 같은 fallback 코드를 생성해 제공합니다.
• 서버가 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}");

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

​

처리 패턴

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