> ## 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 couvrant les défaillances temporaires, les entrées non valides et les situations où le système passe en mode hors connexion au lieu de retourner 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 retourner une erreur.

Game Saves fonctionne de l'une de deux façons 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 façon sur XBOX et Windows.
* **En processus** : le SDK effectue lui-même la synchronisation infonuagique, 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 en mode hors connexion au lieu de retourner une erreur?

Le mode hors connexion est un résultat **réussi**, 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()` retourne `false`. Vous obtenez tout de même un dossier de sauvegarde local utilisable.

Une annulation délibérée (**Cancel**) par le joueur se termine plutôt avec `E_PF_GAMESAVE_USER_CANCELLED` et ne fournit **aucun** dossier de sauvegarde. Traitez ce cas comme « ne pas permettre de jouer ». Si votre jeu annule lui-même l'opération asynchrone avec `XAsyncCancel`, celle-ci 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-CA/services/playfab/player-progression/game-saves/offline#when-game-saves-enters-offline-mode-or-returns-an-error).

## `PFGameSaveFilesInitialize` peut-elle échouer de façon temporaire?

**Non.** `PFGameSaveFilesInitialize` ne fait que valider ses arguments et configurer l'état. Elle n'utilise pas le réseau. Chaque échec qu'elle retourne est déterministe :

* `E_INVALIDARG` : un argument requis est manquant ou non valide. En processus, 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 ne servira à 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 plus tard.

## `PFGameSaveFilesAddUserWithUiAsync` peut-elle échouer de façon 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 constate.

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

`PFGameSaveFilesAddUserWithUiAsync` peut également retourner des erreurs **déterministes** qui ne sont pas temporaires et ne peuvent pas être retentées :

* `E_INVALIDARG` : handle ou objet asynchrone nul, ou options contradictoires.
* `E_PF_GAMESAVE_NOT_INITIALIZED` : appelée avant `Initialize`.
* `E_PF_GAMESAVE_USER_ALREADY_ADDED` : l'utilisateur a déjà été ajouté (et est 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 chemins :

* **En processus : oui.** Le basculement hors connexion en cas d'échec temporaire de synchronisation ne se produit que si vous avez inscrit un rappel d'échec de synchronisation (au moyen de `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 offre 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 de détails sur les rappels et l'interface utilisateur système intégrée, consultez [Rappels d'interface utilisateur de Game Saves](/fr-CA/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 seulement.** Avant que l'interface utilisateur de synchronisation puisse s'afficher, `PFGameSaveFilesAddUserWithUiAsync` collecte la configuration du service et (facultativement) connecte l'utilisateur. Des défaillances précoces de configuration, par exemple l'indisponibilité momentanée du service de la plateforme ou un 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 (relancez l'ensemble de `PFGameSaveFilesAddUserWithUiAsync` un peu plus tard); d'autres indiquent des problèmes de configuration (déterministes). Les échecs de connexion ou de jeton sont gérés de façon appropriée et ne font pas échouer l'appel à eux seuls.

En processus, `AddUserWithUiAsync` ne comporte pas cette catégorie de défaillances précoces. Les défaillances surviennent pendant la synchronisation et passent par l'interface utilisateur d'échec de synchronisation (sous réserve de l'exigence de rappel ci-dessus).

## Un téléversement peut-il être annulé?

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

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

* **Réussite** (`S_OK`) : sauvegardé dans le nuage.
* **Annulé** (`E_PF_GAMESAVE_USER_CANCELLED`) : le joueur a annulé.
* **Annulé par votre jeu** (`E_ABORT`) : votre jeu a appelé `XAsyncCancel` sur le téléversement.
* **Échec** : tous les autres cas (par exemple, `E_PF_GAMESAVE_NETWORK_FAILURE` ou `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE`).

Un téléversement peut tout de même se terminer avec la session **hors connexion**. Il se termine avec `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`, et `PFGameSaveFilesIsConnectedToCloud()` retourne ensuite `false`, lorsque la session était déjà hors connexion, lorsque le nuage 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 téléversement antérieur partiellement échoué. Consultez [Lorsqu'un téléversement met la session hors connexion](/fr-CA/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 échecs afin de pouvoir distinguer « le joueur a annulé » de « le téléversement 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 que « vous avez transmis une valeur incorrecte » plutôt qu'un problème temporaire?

| Résultat | Signification | Possibilité de réessayer? |
| - | - | - |
| `E_INVALIDARG` | Argument incorrect (pointeur nul, dossier de sauvegarde non valide ou manquant, options contradictoires). | Non; corrigez l'appel. |
| `E_PF_GAMESAVE_NOT_INITIALIZED` / `E_PF_GAMESAVE_ALREADY_INITIALIZED` | Appel effectué 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 téléversement; 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 contradictoire est déjà en cours pour cet utilisateur : un autre téléversement ou une réinitialisation infonuagique (pour les téléversements et l'ajout d'utilisateur), ou tout téléversement, 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 toujours 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`. | Seulement si votre jeu relance l'opération. |

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

## Recommandations

* Traitez les échecs de `PFGameSaveFilesInitialize` comme des **bogues à corriger** (arguments ou configuration incorrects), et non comme des conditions d'exécution à retenter.
* **En processus :** inscrivez toujours vos rappels d'interface utilisateur (au minimum le rappel d'échec de synchronisation) avant `PFGameSaveFilesAddUserWithUiAsync`, afin que les défaillances temporaires offrent au joueur les options Retry/Use Offline au lieu d'une erreur bloquante.
* **Hors processus :** préparez-vous à un échec brut de `PFGameSaveFilesAddUserWithUiAsync` avant toute interface utilisateur (service ou configuration). Retentez les échecs temporaires; signalez les problèmes de configuration comme des erreurs.
* Conditionnez le 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 ou échec sans dossier → bloquez le jeu.

## Contenu connexe

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


## Related topics

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