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

# FAQ sur la gestion des erreurs de Game Saves

> FAQ sur la gestion des erreurs de Game Saves : défaillances temporaires, entrées non valides et situations où le système passe hors connexion au lieu de renvoyer une erreur.

# FAQ sur la gestion des erreurs de Game Saves

Cet article répond aux questions courantes sur la façon dont Game Saves signale les défaillances : quelles erreurs sont **temporaires** (elles valent la peine d'être retentées), lesquelles signifient que **vous avez transmis une valeur incorrecte** (corrigez l'appel), et quand le système passe en **mode hors connexion** au lieu de renvoyer une erreur.

Game Saves fonctionne de l'une des deux manières suivantes selon la plateforme, et la gestion des erreurs diffère légèrement entre les deux :

* **Hors processus** : le service intégré de la plateforme effectue la synchronisation et affiche sa propre interface utilisateur système. Game Saves fonctionne toujours de cette manière sur XBOX et Windows.
* **In-process** : le SDK effectue lui-même la synchronisation cloud, sur les plateformes où le service de la plateforme n'est pas disponible (par exemple Steam Deck). Votre jeu pilote l'interface utilisateur au moyen de rappels.

## Quand Game Saves passe-t-il hors connexion au lieu de renvoyer une erreur ?

Le mode hors connexion est un résultat de **réussite**, et non une erreur. La synchronisation initiale (`PFGameSaveFilesAddUserWithUiAsync`) ne passe en mode hors connexion que lorsque le joueur choisit explicitement **Use Offline / Play offline** dans une invite d'échec de synchronisation (ou lorsqu'un autre appareil devient l'appareil actif). Dans ce cas, l'opération asynchrone se termine avec `S_OK` et `PFGameSaveFilesIsConnectedToCloud()` renvoie `false`. Vous obtenez tout de même un dossier de sauvegarde local utilisable.

Une **annulation** (**Cancel**) délibérée par le joueur se termine en revanche avec `E_PF_GAMESAVE_USER_CANCELLED` et ne fournit **aucun** dossier de sauvegarde : traitez ce cas comme « ne pas autoriser le jeu ». Si votre jeu annule lui-même l'opération asynchrone avec `XAsyncCancel`, elle se termine plutôt avec `E_ABORT`, également sans dossier de sauvegarde ; traitez `E_ABORT` comme votre propre annulation.

Pour consulter la table de décision complète et la référence des codes d'erreur, consultez [Mode hors connexion de Game Saves](/fr/services/playfab/player-progression/game-saves/offline#when-game-saves-enters-offline-mode-or-returns-an-error).

## `PFGameSaveFilesInitialize` peut-elle échouer de manière temporaire ?

**Non.** `PFGameSaveFilesInitialize` se contente de valider ses arguments et d'initialiser l'état ; elle n'accède pas au réseau. Toutes les défaillances qu'elle renvoie sont déterministes :

* `E_INVALIDARG` : un argument requis est manquant ou non valide. En mode in-process, cela inclut un `saveFolder` manquant ou non valide (un dossier valide est requis sur ces plateformes ; sur XBOX/GDK, l'emplacement est fixe et l'argument est ignoré).
* `E_PF_GAMESAVE_ALREADY_INITIALIZED` : vous l'avez appelée deux fois sans appel intermédiaire à `PFGameSaveFilesUninitializeAsync`.

Si `Initialize` échoue, réessayer n'y changera rien : corrigez l'entrée. Si elle réussit une fois pour une configuration donnée, elle ne commencera pas à échouer d'elle-même par la suite.

## `PFGameSaveFilesAddUserWithUiAsync` peut-elle échouer de manière temporaire ?

**Oui** : c'est l'appel qui effectue la synchronisation réseau ; il peut donc rencontrer des défaillances temporaires (réseau indisponible, erreurs de service, actualisation de jeton, espace disque insuffisant). Les appels HTTP sont retentés selon les paramètres de nouvelle tentative HTTP du titre (`PFHttpRetrySettings`), mais rien ne garantit qu'une défaillance temporaire soit résolue avant que votre jeu ne la voie.

Lorsqu'une défaillance temporaire n'est pas résolue par ces nouvelles tentatives, elle est signalée via l'**interface utilisateur d'échec de synchronisation**, où le joueur choisit **Retry**, **Use Offline** ou **Cancel**. En mode in-process sans rappel d'échec de synchronisation inscrit, elle est renvoyée sous forme de HRESULT brut. Une défaillance temporaire aboutit donc normalement à un mode en ligne, à un mode hors connexion ou à une annulation plutôt qu'à une erreur brute, **avec une différence importante entre les deux modes** (voir la question suivante).

`PFGameSaveFilesAddUserWithUiAsync` peut également renvoyer des erreurs **déterministes** qui ne sont ni temporaires ni susceptibles d'être retentées :

* `E_INVALIDARG` : handle ou async null, ou options contradictoires.
* `E_PF_GAMESAVE_NOT_INITIALIZED` : appelée avant `Initialize`.
* `E_PF_GAMESAVE_USER_ALREADY_ADDED` : l'utilisateur est déjà ajouté (et toujours connecté).

## Dois-je inscrire des rappels d'interface utilisateur pour obtenir l'option hors connexion ?

C'est la principale différence entre les deux modes :

* **In-process : oui.** Le repli hors connexion en cas d'échec temporaire de synchronisation ne se produit que si vous avez inscrit un rappel d'échec de synchronisation (via `PFGameSaveFilesSetUiCallbacks`) avant d'appeler `PFGameSaveFilesAddUserWithUiAsync`. **Si aucun rappel n'est inscrit, une défaillance temporaire termine l'opération avec le HRESULT d'erreur brut : il n'y a ni Retry ni Use Offline.** Sur les plateformes sans interface utilisateur Game Saves intégrée, l'inscription des rappels est obligatoire.
* **Hors processus : pas pour les échecs de synchronisation ordinaires.** L'interface utilisateur système intégrée de la plateforme propose automatiquement les choix **Try again** / **Play offline** ; les défaillances réseau ordinaires pendant la synchronisation offrent donc au joueur une option hors connexion sans aucun rappel du jeu. Vous pouvez tout de même inscrire des rappels pour fournir votre propre interface utilisateur.

Pour plus d'informations sur les rappels et l'interface utilisateur système intégrée, consultez [Rappels d'interface utilisateur de Game Saves](/fr/services/playfab/player-progression/game-saves/ui-callbacks).

## Existe-t-il des défaillances qui se produisent *avant* l'affichage de toute interface utilisateur ?

**Hors processus uniquement.** Avant que l'interface utilisateur de synchronisation puisse s'afficher, `PFGameSaveFilesAddUserWithUiAsync` récupère la configuration du service et (éventuellement) connecte l'utilisateur. Des défaillances précoces lors de la configuration (par exemple, le service de la plateforme momentanément indisponible ou le titre non configuré pour Game Saves) peuvent terminer l'appel avec un HRESULT brut avant l'affichage de toute boîte de dialogue. Certaines sont temporaires (réessayez l'intégralité de `PFGameSaveFilesAddUserWithUiAsync` un peu plus tard) ; d'autres indiquent des problèmes de configuration (déterministes). Les défaillances de connexion ou de jeton sont gérées correctement et ne font pas échouer l'appel à elles seules.

En mode in-process, `AddUserWithUiAsync` ne présente pas cette catégorie de défaillances précoces : les défaillances se produisent pendant la synchronisation et passent par l'interface utilisateur d'échec de synchronisation (sous réserve de l'exigence de rappel mentionnée ci-dessus).

## Un chargement peut-il être annulé ?

**Oui.** `PFGameSaveFilesUploadWithUiAsync` affiche une interface utilisateur (un indicateur de progression, et une invite d'échec de synchronisation en cas d'erreur), et le joueur peut quitter l'une ou l'autre. Dans ce cas, l'opération se termine avec `E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`) et la sauvegarde n'est **pas** chargée.

Contrairement à la synchronisation initiale, un chargement n'a pas de résultat de réussite **Use Offline**. Ses résultats finaux sont les suivants :

* **Réussite** (`S_OK`) : enregistré dans le cloud.
* **Annulé** (`E_PF_GAMESAVE_USER_CANCELLED`) : le joueur a annulé.
* **Annulé par votre jeu** (`E_ABORT`) : votre jeu a appelé `XAsyncCancel` sur le chargement.
* **Échec** : tous les autres cas (par exemple `E_PF_GAMESAVE_NETWORK_FAILURE` ou `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE`).

Un chargement peut tout de même se terminer avec la session **hors connexion**. Il se termine avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`, et `PFGameSaveFilesIsConnectedToCloud()` renvoie ensuite `false`, lorsque la session était déjà hors connexion, lorsque le cloud contient une sauvegarde plus récente provenant d'un autre appareil, ou lorsque le joueur choisit **Use Offline** dans l'invite de reverrouillage qui suit un chargement précédent partiellement échoué. Consultez [Quand un chargement met la session hors connexion](/fr/services/playfab/player-progression/game-saves/offline#when-an-upload-takes-the-session-offline).

Traitez `E_PF_GAMESAVE_USER_CANCELLED` séparément des autres défaillances afin de distinguer « le joueur a annulé » de « le chargement a échoué ». Il s'agit du même code d'annulation que celui utilisé par la synchronisation initiale : une seule vérification couvre donc les deux opérations.

## Quelles erreurs indiquent « vous avez transmis une valeur incorrecte » plutôt qu'un problème temporaire ?

| Résultat | Signification | Nouvelle tentative possible ? |
| - | - | - |
| `E_INVALIDARG` | Argument incorrect (pointeur null, dossier de sauvegarde non valide ou manquant, options contradictoires). | Non : corrigez l'appel. |
| `E_PF_GAMESAVE_NOT_INITIALIZED` / `E_PF_GAMESAVE_ALREADY_INITIALIZED` | Appel dans le mauvais ordre. | Non : corrigez la séquence. |
| `E_PF_GAMESAVE_USER_ALREADY_ADDED` / `E_PF_GAMESAVE_USER_NOT_ADDED` | État incorrect pour cet appel. | Non : corrigez la séquence. |
| L'interface utilisateur d'échec de synchronisation se déclenche pendant `AddUserWithUiAsync` | Défaillance temporaire du réseau ou du service. | Oui : Retry, ou Use Offline. |
| `E_PF_GAMESAVE_NETWORK_FAILURE` (de `PFGameSaveFilesUploadWithUiAsync`) | Échec temporaire du chargement ; toujours connecté. | Oui : réessayez plus tard. |
| `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` | Vous êtes en mode hors connexion. | Non : vous avez choisi le mode hors connexion (ou perdu le statut d'appareil actif). |
| `E_PF_GAMESAVE_DISK_FULL` | Espace disque local insuffisant. | Une fois que le joueur a libéré de l'espace. |
| `E_PF_GAMESAVE_OPERATION_IN_PROGRESS` | Une opération en conflit est déjà en cours pour cet utilisateur : un autre chargement ou une réinitialisation du cloud (pour les chargements et l'ajout d'utilisateur), ou tout chargement, téléchargement ou réinitialisation (pour `PFGameSaveFilesResetCloudAsync`). | Oui : une fois l'opération en cours terminée. |
| `E_PF_GAMESAVE_LOCAL_FILE_UNAVAILABLE` (de `PFGameSaveFilesUploadWithUiAsync`) | Un fichier de sauvegarde local n'a pas pu être lu (par exemple, il est encore ouvert en écriture). | Oui : une fois que le titre a cessé d'écrire dans le fichier. |
| `E_PF_GAMESAVE_USER_CANCELLED` | Le joueur a annulé dans une invite de l'interface utilisateur. | Non. |
| `E_ABORT` | Votre jeu a annulé l'opération asynchrone avec `XAsyncCancel`. | Uniquement si votre jeu relance l'opération. |

Consultez la référence complète des HRESULT dans [Mode hors connexion de Game Saves](/fr/services/playfab/player-progression/game-saves/offline#game-saves-error-codes).

## Recommandations

* Traitez les défaillances de `PFGameSaveFilesInitialize` comme des **bogues à corriger** (arguments ou configuration incorrects), et non comme des conditions d'exécution à retenter.
* **In-process :** inscrivez toujours vos rappels d'interface utilisateur (au minimum le rappel d'échec de synchronisation) avant `PFGameSaveFilesAddUserWithUiAsync`, afin que les défaillances temporaires proposent au joueur Retry/Use Offline plutôt qu'une erreur bloquante.
* **Hors processus :** préparez-vous à une défaillance brute de `PFGameSaveFilesAddUserWithUiAsync` avant toute interface utilisateur (service/configuration). Réessayez en cas de défaillance temporaire ; signalez les problèmes de configuration comme des erreurs.
* Conditionnez l'accès au jeu au résultat final : `S_OK` + connecté → jeu en ligne ; `S_OK` + non connecté → jeu hors connexion (avertissez le joueur que les sauvegardes ne seront pas synchronisées) ; annulation/échec sans dossier → bloquez l'accès au jeu.

## Contenu associé

* [Mode hors connexion de Game Saves](/fr/services/playfab/player-progression/game-saves/offline)
* [Rappels d'interface utilisateur de Game Saves](/fr/services/playfab/player-progression/game-saves/ui-callbacks)
* [Conflits de Game Saves](/fr/services/playfab/player-progression/game-saves/conflicts)
* [Changements d'appareil actif dans Game Saves](/fr/services/playfab/player-progression/game-saves/activedevicechanges)


## Related topics

- [Gestion du stockage XGameSave sur la console (xbstorage.exe)](/fr/tools/tools-console/commandlinetools/xbstorage.md)
- [Gestion des erreurs des places de marché](/fr/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-error-handling.md)
- [Game Saves (sommaire)](/fr/build/core-features/common/game-save/game-saves-toc.md)
- [Vue d'ensemble de Game Saves](/fr/services/playfab/player-progression/game-saves/overview.md)
- [Guide d'implémentation de PlayFab Game Saves sur Steam Deck](/fr/services/playfab/player-progression/game-saves/steam-deck-implementation.md)