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

# Perguntas frequentes sobre tratamento de erros do Game Saves

> Perguntas frequentes sobre tratamento de erros do Game Saves, abrangendo falhas transitórias, entradas inválidas e quando o sistema fica offline em vez de retornar um erro.

# Perguntas frequentes sobre tratamento de erros do Game Saves

Este artigo responde a perguntas comuns sobre como o Game Saves relata falhas: quais erros são **transitórios** (vale a pena tentar novamente), quais significam que **você passou algo errado** (corrija a chamada) e quando o sistema entra no **modo offline** em vez de retornar um erro.

O Game Saves é executado de uma de duas maneiras, dependendo da plataforma, e o tratamento de erros difere ligeiramente entre elas:

* **Fora do processo**: o serviço interno da plataforma executa a sincronização e mostra sua própria interface do sistema. O Game Saves sempre é executado dessa forma no XBOX e no Windows.
* **No processo**: o próprio SDK executa a sincronização com a nuvem, em plataformas onde o serviço da plataforma não está disponível (por exemplo, Steam Deck). Seu jogo controla a interface por meio de retornos de chamada.

## Quando o Game Saves fica offline em vez de retornar um erro?

O modo offline é um resultado de **êxito**, não um erro. A sincronização inicial (`PFGameSaveFilesAddUserWithUiAsync`) só entra no modo offline quando o jogador escolhe explicitamente **Use Offline / Play offline** em um aviso de falha de sincronização (ou quando outro dispositivo se torna o dispositivo ativo). Nesse caso, a operação assíncrona é concluída com `S_OK` e `PFGameSaveFilesIsConnectedToCloud()` retorna `false`. Você ainda obtém uma pasta de salvamento local utilizável.

Já um **Cancel** deliberado do jogador é concluído com `E_PF_GAMESAVE_USER_CANCELLED` e **não** fornece uma pasta de salvamento. Trate isso como "não permitir jogar". Se o seu jogo cancelar a operação assíncrona por conta própria com `XAsyncCancel`, ela será concluída com `E_ABORT`, também sem pasta de salvamento; trate `E_ABORT` como seu próprio cancelamento.

Para ver a tabela de decisão completa e a referência de códigos de erro, consulte [Modo offline do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/offline#when-game-saves-enters-offline-mode-or-returns-an-error).

## `PFGameSaveFilesInitialize` pode falhar de forma transitória?

**Não.** `PFGameSaveFilesInitialize` apenas valida seus argumentos e configura o estado. Ele não acessa a rede. Todas as falhas que ele retorna são determinísticas:

* `E_INVALIDARG`: um argumento obrigatório está ausente ou é inválido. No processo, isso inclui um `saveFolder` ausente ou inválido (uma pasta válida é obrigatória nessas plataformas; no XBOX/GDK, o local é fixo e o argumento é ignorado).
* `E_PF_GAMESAVE_ALREADY_INITIALIZED`: você o chamou duas vezes sem uma chamada intermediária a `PFGameSaveFilesUninitializeAsync`.

Se `Initialize` falhar, tentar novamente não ajudará. Corrija a entrada. Se ele tiver êxito uma vez para uma determinada configuração, não começará a falhar mais tarde por conta própria.

## `PFGameSaveFilesAddUserWithUiAsync` pode falhar de forma transitória?

**Sim.** Esta é a chamada que executa a sincronização pela rede, portanto pode encontrar falhas transitórias (rede indisponível, erros de serviço, atualização de token, falta de espaço em disco). As chamadas HTTP são repetidas de acordo com as configurações de repetição HTTP do título (`PFHttpRetrySettings`), mas não há garantia de que uma falha transitória seja resolvida antes que seu jogo a perceba.

Quando uma falha transitória não é resolvida por essas repetições, ela é exibida por meio da **interface de falha de sincronização**, na qual o jogador escolhe **Retry**, **Use Offline** ou **Cancel**. No processo e sem retorno de chamada de falha de sincronização registrado, ela retorna como um HRESULT bruto. Portanto, uma falha transitória normalmente resulta em online, offline ou cancelamento, em vez de um erro bruto, **com uma diferença importante entre os dois caminhos** (consulte a próxima pergunta).

`PFGameSaveFilesAddUserWithUiAsync` também pode retornar erros **determinísticos** que não são transitórios e não podem ser repetidos:

* `E_INVALIDARG`: identificador/async nulo ou opções conflitantes.
* `E_PF_GAMESAVE_NOT_INITIALIZED`: chamado antes de `Initialize`.
* `E_PF_GAMESAVE_USER_ALREADY_ADDED`: o usuário já foi adicionado (e ainda está conectado).

## Preciso registrar retornos de chamada de interface para obter a opção offline?

Esta é a principal diferença entre os dois caminhos:

* **No processo: sim.** O fallback offline para uma falha transitória de sincronização só acontece se você tiver registrado um retorno de chamada de falha de sincronização (por meio de `PFGameSaveFilesSetUiCallbacks`) antes de chamar `PFGameSaveFilesAddUserWithUiAsync`. **Se nenhum retorno de chamada estiver registrado, uma falha transitória conclui a operação com o HRESULT de erro bruto. Não há Retry nem Use Offline.** Em plataformas sem interface interna do Game Saves, registrar os retornos de chamada é obrigatório.
* **Fora do processo: não para falhas de sincronização comuns.** A interface interna do sistema da plataforma fornece automaticamente as opções **Try again** / **Play offline**, de modo que falhas de rede comuns durante a sincronização oferecem ao jogador uma opção offline sem nenhum retorno de chamada do jogo. Você ainda pode registrar retornos de chamada para fornecer sua própria interface.

Para obter detalhes sobre os retornos de chamada e a interface interna do sistema, consulte [Retornos de chamada de interface do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/ui-callbacks).

## Há falhas que acontecem *antes* de qualquer interface aparecer?

**Somente fora do processo.** Antes que a interface de sincronização possa aparecer, `PFGameSaveFilesAddUserWithUiAsync` coleta a configuração do serviço e (opcionalmente) conecta o usuário. Falhas de configuração inicial, por exemplo, o serviço da plataforma estar momentaneamente indisponível ou o título não estar configurado para o Game Saves, podem concluir a chamada com um HRESULT bruto antes que qualquer caixa de diálogo seja exibida. Algumas delas são transitórias (repita todo o `PFGameSaveFilesAddUserWithUiAsync` um momento depois); outras indicam problemas de configuração (determinísticas). Falhas de entrada/token são tratadas normalmente e não fazem a chamada falhar por si só.

No processo, `AddUserWithUiAsync` não tem essa categoria de configuração inicial. As falhas ocorrem durante a sincronização e passam pela interface de falha de sincronização (sujeito ao requisito de retorno de chamada acima).

## Um upload pode ser cancelado?

**Sim.** `PFGameSaveFilesUploadWithUiAsync` mostra uma interface (um indicador de progresso e um aviso de falha de sincronização se encontrar um erro), e o jogador pode sair de qualquer um deles. Quando isso acontece, a operação é concluída com `E_PF_GAMESAVE_USER_CANCELLED` (`0x800704C7`) e o salvamento **não** é enviado.

Ao contrário da sincronização inicial, um upload não tem um resultado de êxito **Use Offline**. Seus resultados finais são:

* **Êxito** (`S_OK`): salvo na nuvem.
* **Cancelado** (`E_PF_GAMESAVE_USER_CANCELLED`): o jogador desistiu.
* **Cancelado pelo seu jogo** (`E_ABORT`): seu jogo chamou `XAsyncCancel` no upload.
* **Falha**: todo o resto (por exemplo, `E_PF_GAMESAVE_NETWORK_FAILURE` ou `E_PF_GAMESAVE_DEVICE_NO_LONGER_ACTIVE`).

Um upload ainda pode terminar com a sessão **offline**. Ele é concluído com `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD`, e `PFGameSaveFilesIsConnectedToCloud()` retorna `false` depois, quando a sessão já estava offline, quando a nuvem tem um salvamento mais recente de outro dispositivo ou quando o jogador escolhe **Use Offline** no aviso de novo bloqueio que segue um upload anterior com falha parcial. Consulte [Quando um upload deixa a sessão offline](/pt-BR/services/playfab/player-progression/game-saves/offline#when-an-upload-takes-the-session-offline).

Trate `E_PF_GAMESAVE_USER_CANCELLED` separadamente de outras falhas para que você possa distinguir "o jogador cancelou" de "o upload apresentou erro". Esse é o mesmo código de cancelamento usado pela sincronização inicial, portanto, uma única verificação abrange as duas operações.

## Quais erros indicam "você passou algo errado" em vez de um problema transitório?

| Resultado | Significado | Pode ser repetido? |
| - | - | - |
| `E_INVALIDARG` | Argumento inválido (ponteiro nulo, pasta de salvamento inválida/ausente, opções conflitantes). | Não; corrija a chamada. |
| `E_PF_GAMESAVE_NOT_INITIALIZED` / `E_PF_GAMESAVE_ALREADY_INITIALIZED` | Chamado fora de ordem. | Não; corrija a sequência. |
| `E_PF_GAMESAVE_USER_ALREADY_ADDED` / `E_PF_GAMESAVE_USER_NOT_ADDED` | Estado incorreto para esta chamada. | Não; corrija a sequência. |
| A interface de falha de sincronização é acionada durante `AddUserWithUiAsync` | Falha transitória de rede/serviço. | Sim; Retry ou Use Offline. |
| `E_PF_GAMESAVE_NETWORK_FAILURE` (de `PFGameSaveFilesUploadWithUiAsync`) | Falha transitória de upload; ainda conectado. | Sim; tente novamente mais tarde. |
| `E_PF_GAMESAVE_DISCONNECTED_FROM_CLOUD` | Você está no modo offline. | Não; você escolheu offline (ou perdeu o status de dispositivo ativo). |
| `E_PF_GAMESAVE_DISK_FULL` | Espaço em disco local insuficiente. | Depois que o jogador liberar espaço. |
| `E_PF_GAMESAVE_OPERATION_IN_PROGRESS` | Uma operação conflitante já está em execução para este usuário: outro upload ou uma redefinição da nuvem (para uploads e adição de usuário) ou qualquer upload, download ou redefinição (para `PFGameSaveFilesResetCloudAsync`). | Sim; depois que a operação em andamento for concluída. |
| `E_PF_GAMESAVE_LOCAL_FILE_UNAVAILABLE` (de `PFGameSaveFilesUploadWithUiAsync`) | Não foi possível ler um arquivo de salvamento local (por exemplo, ele ainda está aberto para gravação). | Sim; quando o título parar de gravar o arquivo. |
| `E_PF_GAMESAVE_USER_CANCELLED` | O jogador cancelou em um aviso da interface. | Não. |
| `E_ABORT` | Seu jogo cancelou a operação assíncrona com `XAsyncCancel`. | Somente se o seu jogo iniciar a operação novamente. |

Consulte a referência completa de HRESULT em [Modo offline do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/offline#game-saves-error-codes).

## Recomendações

* Trate falhas de `PFGameSaveFilesInitialize` como **bugs a corrigir** (argumentos/configuração inválidos), e não como condições de tempo de execução a serem repetidas.
* **No processo:** sempre registre seus retornos de chamada de interface (no mínimo, o retorno de chamada de falha de sincronização) antes de `PFGameSaveFilesAddUserWithUiAsync`, para que falhas transitórias ofereçam ao jogador Retry/Use Offline em vez de um erro definitivo.
* **Fora do processo:** esteja preparado para uma falha bruta de `PFGameSaveFilesAddUserWithUiAsync` antes de qualquer interface (serviço/configuração). Repita as transitórias; exiba problemas de configuração como erros.
* Condicione o jogo ao resultado final: `S_OK` + conectado → jogar online; `S_OK` + não conectado → jogar offline (avise o jogador de que os salvamentos não serão sincronizados); cancelamento/falha sem pasta → bloquear o jogo.

## Conteúdo relacionado

* [Modo offline do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/offline)
* [Retornos de chamada de interface do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/ui-callbacks)
* [Conflitos do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/conflicts)
* [Alterações de dispositivo ativo do Game Saves](/pt-BR/services/playfab/player-progression/game-saves/activedevicechanges)


## Related topics

- [Visão geral do Game Saves](/pt-BR/build/core-features/common/game-save/game-saves-overview.md)
- [Perguntas frequentes sobre o GameInput](/pt-BR/build/core-features/common/input/overviews/input-faq.md)
- [Perguntas frequentes sobre o XBOX Game Publisher Insights](/pt-BR/publishing/game-publishing/concepts/game-publisher-insights/game-publisher-insights-faq.md)
- [Perguntas frequentes sobre flighting do XBOX Insider Program](/pt-BR/publishing/game-publishing/publishing-processes/managed-creators/publishing-processes-xbox-flighting-faq.md)
- [Perguntas frequentes sobre o Economy versão 2 (V2)](/pt-BR/services/playfab/economy-monetization/economy-v2/faq.md)