> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Game Saves 오류 처리 FAQ

> 일시적 실패, 잘못된 입력, 그리고 시스템이 오류를 반환하는 대신 오프라인으로 전환되는 경우를 다루는 Game Saves 오류 처리 FAQ입니다.

# Game Saves 오류 처리 FAQ

이 문서에서는 Game Saves가 실패를 보고하는 방식에 대한 일반적인 질문에 답합니다. 어떤 오류가 **일시적**(재시도할 가치가 있음)인지, 어떤 오류가 **잘못된 값을 전달했음**(호출을 수정해야 함)을 의미하는지, 그리고 시스템이 오류를 반환하는 대신 언제 **오프라인 모드**로 진입하는지 설명합니다.

Game Saves는 플랫폼에 따라 두 가지 방식 중 하나로 실행되며, 오류 처리는 두 방식 간에 약간 다릅니다.

* **Out-of-process**: 플랫폼의 기본 제공 서비스가 동기화를 수행하고 자체 시스템 UI를 표시합니다. Game Saves는 XBOX와 Windows에서 항상 이 방식으로 실행됩니다.
* **In-process**: 플랫폼 서비스를 사용할 수 없는 플랫폼(예: Steam Deck)에서는 SDK가 클라우드 동기화를 직접 수행합니다. 게임은 콜백을 통해 UI를 구동합니다.

## Game Saves는 언제 오류를 반환하는 대신 오프라인으로 전환되나요?

오프라인 모드는 오류가 아니라 **성공** 결과입니다. 초기 동기화(`PFGameSaveFilesAddUserWithUiAsync`)는 플레이어가 동기화 실패 프롬프트에서 **Use Offline / Play offline**을 명시적으로 선택한 경우(또는 다른 디바이스가 활성 디바이스가 된 경우)에만 오프라인 모드로 진입합니다. 이 경우 비동기 작업은 `S_OK`로 완료되고 `PFGameSaveFilesIsConnectedToCloud()`는 `false`를 반환합니다. 사용 가능한 로컬 세이브 폴더는 여전히 제공됩니다.

반면 플레이어가 의도적으로 **Cancel**을 선택하면 `E_PF_GAMESAVE_USER_CANCELLED`로 완료되며 세이브 폴더가 **제공되지 않습니다**. 이는 "플레이를 허용하지 않음"으로 처리하세요. 게임이 `XAsyncCancel`로 비동기 작업을 직접 취소하면 대신 `E_ABORT`로 완료되며, 마찬가지로 세이브 폴더가 제공되지 않습니다. `E_ABORT`는 게임 자체의 취소로 처리하세요.

전체 결정 표와 오류 코드 참조는 [Game Saves 오프라인 모드](/ko/services/playfab/player-progression/game-saves/offline#when-game-saves-enters-offline-mode-or-returns-an-error)를 참조하세요.

## `PFGameSaveFilesInitialize`가 일시적으로 실패할 수 있나요?

**아니요.** `PFGameSaveFilesInitialize`는 인수를 검증하고 상태를 설정할 뿐이며 네트워크에 접근하지 않습니다. 반환하는 모든 실패는 결정적입니다.

* `E_INVALIDARG`: 필수 인수가 없거나 잘못되었습니다. In-process에서는 `saveFolder`가 없거나 잘못된 경우도 포함됩니다(해당 플랫폼에서는 유효한 폴더가 필요하며, XBOX/GDK에서는 위치가 고정되어 있으므로 이 인수는 무시됩니다).
* `E_PF_GAMESAVE_ALREADY_INITIALIZED`: 중간에 `PFGameSaveFilesUninitializeAsync` 호출 없이 두 번 호출했습니다.

`Initialize`가 실패하면 재시도해도 소용없으므로 입력을 수정하세요. 특정 구성에 대해 한 번 성공하면 나중에 저절로 실패하기 시작하지 않습니다.

## `PFGameSaveFilesAddUserWithUiAsync`가 일시적으로 실패할 수 있나요?

**예.** 이 호출은 네트워크 동기화를 수행하므로 일시적인 실패(네트워크 중단, 서비스 오류, 토큰 새로 고침, 디스크 공간 부족)가 발생할 수 있습니다. HTTP 호출은 타이틀의 HTTP 재시도 설정(`PFHttpRetrySettings`)에 따라 재시도되지만, 게임이 실패를 확인하기 전에 일시적인 실패가 해결된다는 보장은 없습니다.

이러한 재시도로 일시적인 실패가 해결되지 않으면 **동기화 실패 UI**를 통해 표시되며, 플레이어는 여기서 **Retry**, **Use Offline** 또는 **Cancel**을 선택합니다. 또는 In-process에서 동기화 실패 콜백이 등록되지 않은 경우에는 원시 HRESULT로 반환됩니다. 따라서 일시적인 실패는 일반적으로 원시 오류가 아니라 온라인, 오프라인 또는 취소로 귀결되지만, **두 경로 간에는 한 가지 중요한 차이점이 있습니다**(다음 질문 참조).

`PFGameSaveFilesAddUserWithUiAsync`는 일시적이지 않고 재시도할 수 없는 **결정적** 오류도 반환할 수 있습니다.

* `E_INVALIDARG`: 핸들/비동기 블록이 null이거나 옵션이 충돌합니다.
* `E_PF_GAMESAVE_NOT_INITIALIZED`: `Initialize` 전에 호출되었습니다.
* `E_PF_GAMESAVE_USER_ALREADY_ADDED`: 사용자가 이미 추가되어 있습니다(그리고 여전히 연결되어 있습니다).

## 오프라인 옵션을 사용하려면 UI 콜백을 등록해야 하나요?

이것이 두 경로 간의 핵심 차이점입니다.

* **In-process: 예.** 일시적인 동기화 실패에 대한 오프라인 대체는 `PFGameSaveFilesAddUserWithUiAsync`를 호출하기 전에 (`PFGameSaveFilesSetUiCallbacks`를 통해) 동기화 실패 콜백을 등록한 경우에만 발생합니다. **콜백이 등록되지 않은 경우 일시적인 실패가 발생하면 작업이 원시 오류 HRESULT로 완료되며, Retry와 Use Offline이 제공되지 않습니다.** 기본 제공 Game Saves UI가 없는 플랫폼에서는 콜백 등록이 필수입니다.
* **Out-of-process: 일반적인 동기화 실패에는 필요하지 않습니다.** 플랫폼의 기본 제공 시스템 UI가 **Try again** / **Play offline** 선택지를 자동으로 제공하므로, 동기화 중 일반적인 네트워크 실패가 발생하면 게임 콜백 없이도 플레이어에게 오프라인 옵션이 제공됩니다. 자체 UI를 제공하려는 경우 여전히 콜백을 등록할 수 있습니다.

콜백과 기본 제공 시스템 UI에 대한 자세한 내용은 [Game Saves UI 콜백](/ko/services/playfab/player-progression/game-saves/ui-callbacks)을 참조하세요.

## UI가 표시되기 *전에* 발생하는 실패가 있나요?

**Out-of-process에서만 발생합니다.** 동기화 UI가 표시되기 전에 `PFGameSaveFilesAddUserWithUiAsync`는 서비스 구성을 수집하고 (선택적으로) 사용자를 로그인시킵니다. 초기 설정 실패(예: 플랫폼 서비스를 일시적으로 사용할 수 없거나 타이틀이 Game Saves용으로 구성되지 않은 경우)가 발생하면 대화 상자가 표시되기 전에 호출이 원시 HRESULT로 완료될 수 있습니다. 이 중 일부는 일시적이며(잠시 후 `PFGameSaveFilesAddUserWithUiAsync` 전체를 재시도), 나머지는 구성 문제(결정적)를 나타냅니다. 로그인/토큰 실패는 정상적으로 처리되며 그 자체로 호출을 실패시키지 않습니다.

In-process에서 `AddUserWithUiAsync`에는 이러한 초기 설정 범주가 없습니다. 실패는 동기화 중에 발생하며 동기화 실패 UI를 거칩니다(위의 콜백 요구 사항이 적용됨).

## 업로드를 취소할 수 있나요?

**예.** `PFGameSaveFilesUploadWithUiAsync`는 UI(진행률 표시기 및 오류 발생 시 동기화 실패 프롬프트)를 표시하며, 플레이어는 둘 중 어느 것에서든 취소할 수 있습니다. 취소하면 작업은 `E_PF_GAMESAVE_USER_CANCELLED`(`0x800704C7`)로 완료되며 세이브는 업로드되지 **않습니다**.

초기 동기화와 달리 업로드에는 **Use Offline** 성공 결과가 없습니다. 업로드의 종료 결과는 다음과 같습니다.

* **성공**(`S_OK`): 클라우드에 저장되었습니다.
* **취소됨**(`E_PF_GAMESAVE_USER_CANCELLED`): 플레이어가 취소했습니다.
* **게임에서 취소함**(`E_ABORT`): 게임이 업로드에 대해 `XAsyncCancel`을 호출했습니다.
* **실패**: 그 밖의 모든 경우(예: `E_PF_GAMESAVE_NETWORK_FAILURE` 또는 `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE`)입니다.

업로드가 세션이 **오프라인**인 상태로 끝날 수도 있습니다. 세션이 이미 오프라인이었거나, 클라우드에 다른 디바이스의 더 최신 세이브가 있거나, 이전에 부분적으로 실패한 업로드에 이어지는 다시 잠금 프롬프트에서 플레이어가 **Use Offline**을 선택한 경우, 업로드는 `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`로 완료되며 이후 `PFGameSaveFilesIsConnectedToCloud()`는 `false`를 반환합니다. [업로드로 인해 세션이 오프라인이 되는 경우](/ko/services/playfab/player-progression/game-saves/offline#when-an-upload-takes-the-session-offline)를 참조하세요.

"플레이어가 취소함"과 "업로드 오류 발생"을 구분할 수 있도록 `E_PF_GAMESAVE_USER_CANCELLED`를 다른 실패와 별도로 처리하세요. 이는 초기 동기화에서 사용하는 것과 동일한 취소 코드이므로 한 번의 확인으로 두 작업을 모두 처리할 수 있습니다.

## 어떤 오류가 "잘못된 값을 전달함"을 나타내고, 어떤 오류가 일시적인 문제를 나타내나요?

| 결과 | 의미 | 재시도 가능 여부 |
| - | - | - |
| `E_INVALIDARG` | 잘못된 인수(null 포인터, 잘못되었거나 누락된 세이브 폴더, 충돌하는 옵션). | 아니요. 호출을 수정하세요. |
| `E_PF_GAMESAVE_NOT_INITIALIZED` / `E_PF_GAMESAVE_ALREADY_INITIALIZED` | 순서에 맞지 않게 호출되었습니다. | 아니요. 호출 순서를 수정하세요. |
| `E_PF_GAMESAVE_USER_ALREADY_ADDED` / `E_PF_GAMESAVE_USER_NOT_ADDED` | 이 호출에 맞지 않는 상태입니다. | 아니요. 호출 순서를 수정하세요. |
| `AddUserWithUiAsync` 중 동기화 실패 UI가 실행됨 | 일시적인 네트워크/서비스 실패입니다. | 예. Retry 또는 Use Offline을 선택합니다. |
| `E_PF_GAMESAVE_NETWORK_FAILURE`(`PFGameSaveFilesUploadWithUiAsync`에서 반환) | 일시적인 업로드 실패이며, 여전히 연결되어 있습니다. | 예. 나중에 다시 시도하세요. |
| `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` | 오프라인 모드 상태입니다. | 아니요. 오프라인을 선택했거나 활성 디바이스 상태를 잃었습니다. |
| `E_PF_GAMESAVE_DISK_FULL` | 로컬 디스크 공간이 부족합니다. | 플레이어가 공간을 확보한 후 가능합니다. |
| `E_PF_GAMESAVE_OPERATION_IN_PROGRESS` | 이 사용자에 대해 충돌하는 작업이 이미 실행 중입니다. 업로드 및 사용자 추가의 경우 다른 업로드 또는 클라우드 재설정, `PFGameSaveFilesResetCloudAsync`의 경우 모든 업로드, 다운로드 또는 재설정이 해당됩니다. | 예. 진행 중인 작업이 완료된 후 가능합니다. |
| `E_PF_GAMESAVE_LOCAL_FILE_UNAVAILABLE`(`PFGameSaveFilesUploadWithUiAsync`에서 반환) | 로컬 세이브 파일을 읽을 수 없습니다(예: 여전히 쓰기 위해 열려 있는 경우). | 예. 타이틀이 파일 쓰기를 멈춘 후 가능합니다. |
| `E_PF_GAMESAVE_USER_CANCELLED` | 플레이어가 UI 프롬프트에서 취소했습니다. | 아니요. |
| `E_ABORT` | 게임이 `XAsyncCancel`로 비동기 작업을 취소했습니다. | 게임이 작업을 다시 시작하는 경우에만 가능합니다. |

전체 HRESULT 참조는 [Game Saves 오프라인 모드](/ko/services/playfab/player-progression/game-saves/offline#game-saves-error-codes)를 참조하세요.

## 권장 사항

* `PFGameSaveFilesInitialize` 실패는 재시도할 런타임 조건이 아니라 **수정해야 할 버그**(잘못된 인수/구성)로 처리하세요.
* **In-process:** 일시적인 실패 시 하드 오류 대신 플레이어에게 Retry/Use Offline이 제공되도록, `PFGameSaveFilesAddUserWithUiAsync` 전에 항상 UI 콜백(최소한 동기화 실패 콜백)을 등록하세요.
* **Out-of-process:** UI가 표시되기 전에 `PFGameSaveFilesAddUserWithUiAsync`에서 원시 실패(서비스/구성)가 발생할 수 있음에 대비하세요. 일시적인 실패는 재시도하고, 구성 문제는 오류로 표시하세요.
* 최종 결과에 따라 플레이를 제어하세요. `S_OK` + 연결됨 → 온라인으로 플레이, `S_OK` + 연결되지 않음 → 오프라인으로 플레이(세이브가 동기화되지 않는다고 플레이어에게 경고), 폴더 없이 취소/실패 → 플레이 차단.

## 관련 콘텐츠

* [Game Saves 오프라인 모드](/ko/services/playfab/player-progression/game-saves/offline)
* [Game Saves UI 콜백](/ko/services/playfab/player-progression/game-saves/ui-callbacks)
* [Game Saves 충돌](/ko/services/playfab/player-progression/game-saves/conflicts)
* [Game Saves 활성 디바이스 변경](/ko/services/playfab/player-progression/game-saves/activedevicechanges)


## Related topics

- [Game Saves 오프라인 모드](/ko/services/playfab/player-progression/game-saves/offline.md)
- [Game Saves 롤백](/ko/services/playfab/player-progression/game-saves/rollback.md)
- [Game Saves 개요](/ko/services/playfab/player-progression/game-saves/overview.md)
- [Marketplace 오류 처리](/ko/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-error-handling.md)
- [PlayFab Game Saves용 Steam Deck 구현 가이드](/ko/services/playfab/player-progression/game-saves/steam-deck-implementation.md)