> ## 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.

# 에러 처리

> SDK 오류를 구분하고 플레이어에게 적절한 메시지를 보여주는 방법입니다.

HyperX API 요청이 실패하면 SDK는 대부분 `HyperXServerException`을 발생시킵니다. 초기화 자체의 실패는 `HyperXInitializationException`으로 분리됩니다.

## 기본 패턴

```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")
    {
        // 기본 설정을 사용하거나 운영자에게 파일 업로드를 요청합니다.
    }
}
```

## 확인할 수 있는 정보

| 필드              | 용도                                         |
| --------------- | ------------------------------------------ |
| `ErrorCode`     | 코드에서 분기하기 좋은 안정적인 오류 코드입니다.                |
| `ServerMessage` | 서버가 전달한 사람이 읽을 수 있는 메시지입니다.                |
| `StatusCode`    | HTTP 상태 코드입니다.                             |
| `TraceId`       | 서버 로그와 연결할 때 쓰는 추적 ID입니다.                  |
| `RequestId`     | 요청 한 건을 식별하는 ID입니다.                        |
| `Context`       | 파일명, 테이블 키, provider 등 오류 원인 파악에 필요한 값입니다. |

플레이어에게는 원본 서버 메시지보다 게임에 맞는 문구를 보여주세요. 예를 들어 결제 검증 실패는 “구매 확인에 실패했습니다. 잠시 후 다시 시도해주세요.”처럼 안내하고, `TraceId`와 `RequestId`는 고객지원용 로그에 남깁니다.

## 자주 처리하는 오류

| 상황        | 대표 코드                      | 권장 처리                                |
| --------- | -------------------------- | ------------------------------------ |
| 로그인 필요    | `UNAUTHORIZED`             | 세션 갱신 후 다시 시도하고, 실패하면 로그인 화면으로 보냅니다. |
| 파일 없음     | `STORAGE_OBJECT_NOT_FOUND` | 기본 리소스를 사용하거나 Console 업로드 상태를 확인합니다. |
| 데이터 검증 실패 | `VALIDATION_ERROR`         | 저장하려는 JSON과 Console 스키마를 맞춥니다.       |
| 소셜 토큰 오류  | `INVALID_PROVIDER_TOKEN`   | 플랫폼 SDK에서 새 토큰을 받은 뒤 다시 로그인합니다.      |
| 채팅 권한 오류  | `CHAT_SENDER_MUTED`        | 채팅 입력을 막고 뮤트 안내를 표시합니다.              |

## 다운로드 오류

`PublicStorage.Get(...)`은 다운로드 진행 객체를 먼저 반환합니다. 실제 실패는 `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}");
}
```