> For the complete documentation index, see [llms.txt](/llms.txt)

# Implementation Patterns for Error Handling

Best practices for practical error handling and retry strategies in game development using GS2.




In network feature implementation using GS2, error handling directly impacts game stability and user experience (UX). Here are some practical implementation patterns that go beyond simple exception catching.

## 1. Error Classification and Handling Policy

GS2 exceptions can be broadly classified into three categories based on their nature.

| Category | Applicable Exceptions (Example) | Handling Policy |
| --- | --- | --- |
| **Transient Errors** | `InternalServerError`, `ServiceUnavailable`, `RequestTimeout` | **Automatic Retry**. If it fails after several attempts, display an error dialog. |
| **Logic/Configuration Errors** | `BadRequest`, `NotFound` | **Errors to be resolved during development**. After release, collect logs as bugs and display appropriate messages to users. |
| **Auth/State Errors** | `Unauthorized`, `Conflict`, `QuotaLimitExceeded` | **Special recovery processing** required. Perform re-login or data resynchronization (re-acquisition of domain objects). |

## 2. Implementing Retry Strategy (Exponential Backoff)

For errors caused by server overload or temporary network instability, "Exponential Backoff," where retries are spaced out at increasing intervals, is recommended rather than immediate retries.

### Example in Unity / C# (Automatic Retry)

```csharp
public async Task<T> ExecuteWithAutoRetry<T>(Func<Task<T>> action, int maxRetries = 3)
{
    for (int i = 0; i < maxRetries; i++)
    {
        try
        {
            return await action();
        }
        catch (Gs2.Core.Exception.Gs2Exception e) when (e.RecommendAutoRetry) // Check if automatic retry is recommended
        {
            if (i == maxRetries - 1) throw;

            // Exponential Backoff: 1s, 2s, 4s...
            await Task.Delay((int)Math.Pow(2, i) * 1000);
        }
    }
    throw new Exception("Reached unreachable code");
}
```

### Determining Manual Retry

If `RecommendAutoRetry` is `false` and `RecommendRetry` is `true` (e.g., `ConflictException` or `QuotaLimitExceededException`), repeating automatically many times may worsen the situation. Therefore, it is common to display a dialog to the user prompting them to retry manually.

## 3. Automatic Recovery from Authentication Errors (`UnauthorizedException`)

When an `UnauthorizedException` occurs due to an expired access token, ideally, the application should automatically log back in in the background and retry the request rather than prompting the user to return to the title screen.

### Implementation Image

```csharp
try
{
    await gs2.Inventory.Namespace("...").Me(GameSession).Inventory("...").ModelAsync();
}
catch (Gs2.Core.Exception.UnauthorizedException)
{
    // 1. Execute re-login process in the background
    GameSession = await ReLogin();
    
    // 2. Retry the request using the new GameSession
    await gs2.Inventory.Namespace("...").Me(GameSession).Inventory("...").ModelAsync();
}
```

## 4. Resolving Conflicts (`ConflictException`)

A `ConflictException` may occur if the connection is interrupted during the execution of a stamp sheet. This indicates that "the previous process is not yet complete on the server side, or is duplicated."

- **Workaround**: In many cases, it is resolved by a simple retry. If you are using high-level APIs of the GS2 SDK (Domain objects), there may be an inconsistency between the internal cache and the server state, so it is recommended to re-acquire the Domain object before retrying.

## 5. User Feedback (UX)

Displaying a dialog for every error can be stressful for users.

1.  **Silent Retry**: For transient errors, first retry 1-2 times in the background. During this time, only display a "Communicating..." indicator in the UI.
2.  **Recoverable Dialog**: If the retry still fails, display a message such as "Communication failed. Please try again in a place with good reception" along with **[Retry] [Return to Title]** buttons.
3.  **Fatal Error**: For maintenance or when a forced app version update is required, display a dedicated dialog that provides no option other than returning to the title screen.

## Summary

- Apply **Exponential Backoff** to retryable errors.
- Hide authentication errors with **Automatic Re-login**.
- Enable **Chaos Mode** during development to verify that these handlers are working correctly.