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

# 에러·예외

Game Server Services를 이용하는 과정에서 발생하는 일반적인 에러




GS2가 응답하는 에러는 일정한 규칙에 따라 응답됩니다.
이 규칙을 이해하면 에러 해결을 신속하게 수행할 수 있습니다.

**에러 메시지 예시**
```json
[{"component":"progress","message":"quest.progress.progress.error.notFound"}]
```

| 섹션 | 설명 |
| ------------- | --- |
| component | 에러가 발생한 대상을 나타내며, 멤버 이름, 메서드 이름이 들어갑니다. |
| message | 에러 위치의 상세 내용, 에러를 나타내는 키워드가 들어갑니다. `서비스명`.`컴포넌트`.error.`에러 내용` |

## 주요 에러 내용

| 주요 에러 내용 | 설명 |
| ------------- | --- |
| failed | 처리에 실패했습니다. |
| invalid | 잘못된 파라미터입니다. |
| require | 필요한 인수가 없습니다. |
| tooLong | 인수의 문자 수가 너무 깁니다. |
| tooMany | 배열의 요소 수가 너무 많습니다. |
| exists | 이미 존재합니다. |
| duplicate | 중복, 이미 존재합니다. |
| notFound | 찾을 수 없습니다. |
| notMatch | 일치하지 않습니다. |

## 예외의 종류

SDK에 의해 에러는 어느 정도 분류되며, 발생하는 예외의 유형이 달라집니다.
모든 예외는 `Gs2Exception`을 상속하고 있으며, 다음 속성을 참조함으로써 재시도 필요 여부를 판단할 수 있습니다.

- **RecommendRetry**: 사용자에게 "재시도" 버튼을 표시하는 등, 수동 재시도를 검토해야 하는 에러.
- **RecommendAutoRetry**: 사용자에게 알리지 않고 시스템 측에서 자동으로 재시도해도 안전한 에러.

| 예외 | 에러 내용 | 상태 코드 | RecommendRetry | RecommendAutoRetry |
| ---- | ------- | --------------| :---: | :---: |
| BadRequestException | 요청 내용이 올바르지 않습니다. | 400 | | |
| UnauthorizedException | 권한 인증을 할 수 없었습니다. | 401 | | |
| QuotaLimitExceededException | 쿼터 제한을 초과했습니다. | 402 | ✔︎ | |
| NotFoundException | 대상을 찾을 수 없었습니다. | 404 | | |
| ConflictException | 처리가 충돌했습니다. | 409 | ✔︎ | |
| InternalServerErrorException | 서버에서 에러가 발생했습니다. | 500 | ✔︎ | ✔︎ |
| BadGatewayException | 서버가 잘못된 응답을 받았습니다. | 502 | ✔︎ | ✔︎ |
| ServiceUnavailableException | 서비스에서 일시적인 에러가 발생했습니다. | 503 | ✔︎ | ✔︎ |
| RequestTimeoutException | 요청이 타임아웃되었습니다. | 504 | ✔︎ | ✔︎ |
| UnknownException | 알 수 없는 예외가 발생했습니다. | | | |

`RecommendRetry`가 true인 예외는 요청 파라미터는 정상이지만 서버의 상태에 따라 발생할 수 있는 에러입니다.
이러한 에러를 감지한 경우에는 재시도할 것을 권장합니다.

이때 성공할 때까지 재시도하는 것이 아니라, 일정 횟수나 일정 시간 경과 시 타임아웃되도록 구현할 것을 강력히 권장합니다.
재시도할 때는 요청 사이에 슬립을 넣을 것을 권장하며, 재시도 횟수에 따라 슬립 시간을 늘려나갈 것을 권장합니다.

게임 내에서 핸들링이 필요한 에러에 대해서는, 마이크로서비스별로 나열된 예외를 상속한 에러 고유의 예외 타입을 정의한 경우가 있습니다.
그 경우, 에러 고유의 예외로 에러 핸들링을 하면 더 간편하게 에러 핸들링을 구현할 수 있습니다.
고유의 에러를 표현하는 예외가 존재하는 경우, API 레퍼런스의 메서드 설명에 기재되어 있으므로 그쪽을 참조해 주십시오.

### 클라이언트에서 발생하는 예외의 취득

GS2-CSharp-SDK, GS2 SDK for Unity에서는 접속에 사용하는 게임 엔진/프레임워크에서 발생한 에러 내용의 메시지를 취득할 수 있습니다.

| 예외 | 에러 내용 | 상태 코드 |
| ---- | ------- | -------------- |
| NoInternetConnectionException | 인터넷 접속에 실패했습니다.<br>※단말기가 비행기 모드/전파권 밖/라우터에 연결되어 있지만 외부로 나갈 수 없는 등, 소켓 확립이나 DNS 해석에 실패했을 때의 접속 에러를 포함합니다. | 0 |
| 　ConnectionException | (Unity만 해당)　서버와의 통신에 실패했습니다.<br>요청이 접속할 수 없었거나, 보안이 적용된 채널을 확립할 수 없었던 경우 등. | 0 | |
| 　DataProcessingException | (Unity만 해당)　데이터 처리 중 에러가 발생했습니다. | 0 |
| 　HttpRequestException | (.net만 해당)　HttpRequest에서 에러가 발생했습니다. | 0 |

## 카오스 모드

GS2 C# SDK 및 GS2 SDK for Unity에는 카오스 모드가 탑재되어 있습니다.
카오스 모드를 활성화하면 지정한 비율로 재시도가 필요한 예외를 무작위로 발생시킵니다.

카오스 모드를 활성화한 상태로 개발을 진행함으로써 게임 내 에러 핸들링을 더욱 견고하게 만들 수 있습니다.
카오스 모드 활성화 방법은 [초기화 처리]()를 참조해 주십시오.

## 구현 가이드

보다 구체적인 구현 방법이나 모범 사례에 대해서는 [에러 핸들링 구현 패턴]()을 참조해 주십시오.




- [에러 핸들링 구현 패턴](/ko/articles/tech/error/pattern/)