Implementation Patterns for Error Handling
Best practices for practical error handling and retry strategies in game development using GS2.
Error/Exception
Common errors that occur when using Game Server Services.
GS2 responds to errors according to certain rules. By understanding these rules, you will be able to resolve errors quickly.
Example of an error message
[{"component": "progress", "message": "quest.progress.progress.error.notFound"}]| section | description |
|---|---|
| component | Indicates the target where the error occurred, and contains the member name and method name. |
| message | Details of the error location and keywords that describe the error. serviceName.component.error.errorType |
Major error types
| major error content | description |
|---|---|
| failed | Processing failed. |
| invalid | Illegal parameter. |
| require | Missing required argument. |
| tooLong | Argument is too long. |
| tooMany | Too many array elements. |
| exists | Already exists. |
| duplicate | duplicate, already exists. |
| notFound | Not found. |
| notMatch | No match was found. |
Types of Exceptions
Errors are classified to some extent by SDK, and the type of exception sent out varies.
All exceptions inherit from Gs2Exception, and you can determine whether to retry by referring to the following properties:
- RecommendRetry: Errors for which a manual retry should be considered, such as displaying a “Retry” button to the user.
- RecommendAutoRetry: Errors that are safe for the system to retry automatically without notifying the user.
| Exception | Error Content | Status Code | RecommendRetry | RecommendAutoRetry |
|---|---|---|---|---|
| BadRequestException | Bad request content. | 400 | ||
| UnauthorizedException | Authentication failed. | 401 | ||
| QuotaLimitExceededException | Quota limit exceeded. | 402 | ✔ | |
| NotFoundException | The object could not be found. | 404 | ||
| ConflictException | Processing conflict. | 409 | ✔ | |
| InternalServerErrorException | An error occurred on the server. | 500 | ✔ | ✔ |
| BadGatewayException | The server received an invalid response. | 502 | ✔ | ✔ |
| ServiceUnavailableException | A transient error occurred in the service. | 503 | ✔ | ✔ |
| RequestTimeoutException | Request timed out. | 504 | ✔ | ✔ |
| UnknownException | Unknown exception occurred. |
Exceptions where RecommendRetry is true are errors that may occur due to server conditions, although the request parameters are normal.
When such errors are detected, it is recommended to retry.
It is strongly recommended to implement a timeout after a certain number of times or a certain amount of time, rather than retrying until success. When retrying, it is recommended that a sleep be inserted between requests, and that the length of the sleep be increased according to the number of retries.
For errors that require in-game handling, some microservices define error-specific exception types that inherit from the exceptions enumerated for each microservice. In such cases, error handling can be more easily implemented by using error-specific exceptions. If there are exceptions that represent error-specific errors, please refer to the method descriptions in the API reference.
Retrieving Exceptions Occurring on the Client
The GS2-CSharp-SDK and GS2 SDK for Unity allow you to retrieve the error message content that occurred in the game engine/framework used for the connection.
| Exception | Error Content | Status Code |
|---|---|---|
| NoInternetConnectionException | Failed to connect to the internet. ※ Includes connection errors when socket establishment or DNS resolution fails due to the device being in airplane mode, out of range, or connected to a router but unable to exit the network. |
0 |
| ConnectionException | (Unity only) Failed to communicate with the server. Examples include: the request couldn’t connect, or a secure channel couldn’t be established. |
0 |
| DataProcessingException | (Unity only) An error occurred during data processing. | 0 |
| HttpRequestException | (.NET only) An error occurred during the HttpRequest. | 0 |
Chaos mode
GS2 C# SDK and GS2 SDK for Unity include Chaos Mode. When enabled, chaos mode will randomly emit exceptions that require retries at a specified rate.
By proceeding with development with chaos mode enabled, error handling in the game can be made more robust. See initialization process for how to enable chaos mode.
Implementation Guide
For more specific implementation methods and best practices, see Implementation Patterns for Error Handling.