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

# 일반적인 오류 사례 처리

> 타이틀에서 티켓 취소, 시간 초과, 잘못된 특성, 매치 만들기 실패 등의 일반적인 PlayFab 매치메이킹 오류 사례를 처리합니다.

PlayFab 매치메이킹은 매치메이킹에 진입하고 종료하기 위한 간단한 인터페이스를 제공합니다. 그럼에도 불구하고 계획대로 진행되지 *않을 수도* 있는 여러 지점이 있습니다. 아래에는 몇 가지 더 일반적인 오류 사례와 타이틀이 이를 처리하는 방법이 나와 있습니다.

이 페이지에서는 사용자가 PlayFab 매치메이킹의 일반적인 흐름에 익숙하다고 가정합니다. 자세한 내용은 매치메이킹의 일반적인 사용에 대한 [매치메이킹 빠른 시작](/services/playfab/multiplayer/matchmaking/quickstart)을 참조하세요.

## 티켓 만들기 오류

티켓 만들기는 여러 가지 이유로 실패할 수 있습니다. 이러한 대부분의 경우 PlayFab 오류 코드는 제출 요청에서 잘못된 것을 식별합니다. 이를 수정하면 성공적으로 제출할 수 있습니다.

<Note>
  오류 `MatchmakingAttributeInvalid` 및 `MatchmakingPlayerAttributesInvalid`는 특성 형식과 관련된 문제를 나타냅니다. 자세한 내용은 티켓에서 특성을 전달하는 방법에 대한 세부 정보는 [티켓 특성 지정](/services/playfab/multiplayer/matchmaking/ticket-attributes) 섹션을 참조하세요.
</Note>

다른 오류 코드는 요청은 유효하지만 요청 외부의 상황으로 인해 티켓이 수락되지 않는다는 것을 나타냅니다. 특히 다음과 같습니다.

1. `MatchmakingRateLimitExceeded` - 티켓을 너무 자주 제출했음을 나타냅니다. 자세한 내용은 아래 [섹션](#call-returns-matchmakingratelimitexceeded)을 참조하세요.
2. `MatchmakingTicketMembershipLimitExceeded` - 사용자가 이미 다른 활성 티켓에 있음을 나타냅니다. 사용자는 두 게임을 동시에 플레이할 수 없기 때문에 큐 내에서 한 번에 두 개 이상의 티켓에 있을 수 없도록 제한됩니다. 이 상황을 수정하는 방법에 대한 자세한 내용은 아래 [섹션](#creating-or-joining-a-ticket-returns-matchmakingticketmembershiplimitexceeded)을 참조하세요.

HTTP 오류 코드 503을 받으면 잠시 지연 후에 요청을 다시 시도하세요.

## 호출에서 MatchmakingRateLimitExceeded 반환

다른 PlayFab 기능과 유사하게 PlayFab 매치메이킹은 게임 관리자 내에서 구성된 제한에 따라 호출 수를 제한합니다. `MatchmakingRateLimitExceeded` 오류를 수신하면 타이틀이 이 호출 유형에 대한 제한을 초과했음을 나타냅니다.

매치메이킹에서는 티켓이 매치되었는지 확인하기 위해 [GetMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket)을 폴링할 때 이 오류가 가장 자주 발생합니다.

이 오류를 방지하려면 제한을 늘리거나 호출 빈도를 줄이세요.

<Note>
  응답에 HTTP 상태 코드 429가 있더라도 요청 자체는 유효하며 여전히 다시 시도할 수 있습니다.
</Note>

## 티켓 만들기 또는 참여에서 MatchmakingTicketMembershipLimitExceeded 반환

PlayFab 매치메이킹에서는 사용자가 두 매치에 진입하여 어떤 티켓을 지킬지 결정해야 하는 상황을 피하기 위해 큐당 한 번에 하나의 티켓에만 참여할 수 있습니다. 지켜지지 않은 매치는 플레이어가 부족해지고, 그 플레이어들은 매치메이킹을 다시 진입해야 할 가능성이 큽니다. 사용자가 이미 취소되거나 매치되지 않은 한 티켓에 있으면서 다른 티켓을 만들거나 참여하려고 하면 `MatchmakingTicketMembershipLimitExceeded` 오류가 반환됩니다.

그러나 때때로 타이틀 또는 서버는 크래시, 재시작 또는 기타 예기치 못한 오류로 인해 티켓을 놓칠 수 있습니다. 이 상황이 발생하면 사용자나 타이틀 모두 알지 못하는 활성 티켓이 남게 됩니다.

이 손실된 티켓은 만료될 때까지 이 사용자를 위한 향후 티켓이 제출되지 못하도록 방지합니다. 이 경우 문제를 해결하는 데 사용할 수 있는 두 가지 옵션이 있습니다.

### 옵션 1: 매치메이킹에서 티켓 지우기

사용자의 기존 티켓을 모두 취소합니다. [CancelAllMatchmakingTicketsForPlayer](xref:titleid.playfabapi.com.multiplayer.matchmaking.cancelallmatchmakingticketsforplayer)를 호출하면 이 작업이 수행됩니다. 그 이후에는 매치메이킹에 진행 중인 티켓이 없으며 새 티켓을 만들 준비가 됩니다.

### 옵션 2: 손실된 티켓 찾기

사용자의 기존 티켓을 찾아 계속 사용합니다. [ListMatchmakingTicketsForPlayer](xref:titleid.playfabapi.com.multiplayer.matchmaking.listmatchmakingticketsforplayer)를 호출하면 사용자가 멤버로 있는 모든 매치메이킹 티켓 ID가 반환됩니다. 제공된 각 ticketId에 대해 [GetMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket)을 호출하면 그 상태를 검색하고 매치를 찾을 때까지 모니터링을 계속할 수 있습니다.

## 다중 사용자 티켓에 모든 플레이어가 참여하지 않음

다중 사용자 티켓을 만들 때 초대받은 플레이어 중 한 명이 참여에 실패하거나 거부할 수 있습니다. 이 경우 만들어진 티켓은 만료될 때까지 WaitingForPlayers 상태로 남아 있습니다. 타이틀은 이 상황이 가끔 발생할 것을 예상하고 UI 내에서 상당히 짧은 시간 초과를 설정해야 합니다.

해당 시간 초과 후에 타이틀은 티켓을 취소하고 모든 플레이어가 여전히 함께 게임을 하기로 동의했는지 확인해야 합니다.

## GetMatch에서 찾을 수 없음 반환

매치가 만들어지면 매치는 일정 시간 동안 유지되며 결국 만료됩니다. 매치가 제때 검색되지 않으면 해당 사용자는 다시 매치되기 위해 티켓을 다시 제출해야 합니다. 매치가 적시에(즉, 몇 분 이내) 검색되도록 하면 이 문제를 피할 수 있습니다.

[여기](/services/playfab/multiplayer/lobby/lobby-and-matchmaking)에 설명된 대로 Matchmaking과 Lobby를 함께 사용하는 경우, 여기서 매치가 시간 초과된 후에도 lobbyArrangementString이 일정 기간 동안 유효할 수 있습니다. 만료되기 전에 GetMatch에서 정보를 검색하고 사용해야 합니다.

## 티켓이 취소됨

티켓은 여러 가지 이유로 취소될 수 있습니다. 가장 일반적인 사례는 사용자 취소 및 티켓 만료이지만 서버에서 티켓을 취소할 수도 있습니다. `GetMatchmakingTicket`을 호출하여 티켓이 취소되었음을 알게 되면 그 이유가 `CancellationReason` 필드에 나열됩니다. 가능한 `CancellationReason` 응답과 잠재적인 해결 방법이 아래 나열되어 있습니다.

| CancellationReason     | 설명                                     | 해결 방법                                                     |
| ---------------------- | -------------------------------------- | --------------------------------------------------------- |
| User                   | 사용자가 매치메이킹 티켓을 취소함                     | 의도적. 원하는 경우 새 티켓을 만듭니다.                                   |
| Server                 | 서비스가 서버 API를 통해 매치메이킹 티켓을 취소함          | 의도적. 원하는 경우 새 티켓을 만듭니다.                                   |
| Timeout                | 티켓이 GiveUpAfterSeconds에 도달하여 만료됨       | 새 티켓으로 다시 시도하고 필요한 경우 티켓 특성을 조정합니다.                       |
| ServerAllocationFailed | 큐가 서버를 할당하지만 할당 요청이 실패함                | 대기 서버가 지역에서 사용 가능한지 확인하고 새 티켓으로 다시 시도합니다.                 |
| TicketUnmatchable      | 티켓 매개 변수와 큐의 규칙 조합으로 인해 이 티켓은 매치할 수 없음 | 호환되도록 티켓 특성 또는 큐 구성을 조정합니다.                               |
| RetryRequired          | 내부 일시적 매치메이킹 오류                        | 새 티켓으로 다시 시도하세요. 다음 요청에서 해결될 수 있는 타이밍 문제로 인한 것일 가능성이 큽니다. |
| Internal               | 내부 매치메이킹 서비스 오류                        | 새 티켓으로 다시 시도합니다.                                          |

## 티켓 취소에서 오류 반환

티켓 취소는 성공이 보장되지 않습니다. 대부분의 오류는 자명하지만, 오류 `MatchmakingTicketAlreadyCompleted`는 다음 두 가지 가능성 중 하나를 나타냅니다.

1. 티켓이 이미 취소되었습니다.
2. 티켓이 이미 매치되었습니다.

이 오류를 수신하면 타이틀은 이 두 경우를 구별하기 위해 [GetMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket)을 호출해야 합니다. 첫 번째 경우 티켓이 이미 원하는 상태에 있으며 추가 조치가 필요하지 않습니다. 두 번째 경우는 사용자의 취소가 너무 늦었으며 이미 매치되었음을 나타냅니다. 사용자의 취소와 매치 발견 사이의 이 경합 상태는 피할 수 없으며 타이틀에서 처리해야 합니다.

타이틀에는 이를 해결하기 위한 두 가지 옵션이 있습니다. 즉, 사용자의 취소 요청을 무시하고 어쨌든 매치에 참여하거나, 플레이어가 참여하지 않을 것을 알면서도 매치가 시작되도록 허용합니다. 어느 옵션도 완벽하지 않지만, 이 상황이 발생할 것이라고 예상하고 이에 대한 타이틀 흐름을 의식적으로 만드는 것이 중요합니다. 또한 플레이어가 여러 가지 이유로 매치에 참여하지 않을 수 있으므로, 여기에 언급된 경합 상태에 관계없이 타이틀은 이 사례를 처리해야 합니다.


## Related topics

- [XGameSaveInitializeProvider](/ko/reference/system/xgamesave/functions/xgamesaveinitializeprovider.md)
- [게임 저장 디버깅](/ko/build/core-features/common/game-save/game-saves-debugging.md)
- [XGameSaveGetContainerInfo](/ko/reference/system/xgamesave/functions/xgamesavegetcontainerinfo.md)
- [XGameSaveReadBlobData](/ko/reference/system/xgamesave/functions/xgamesavereadblobdata.md)
- [XGameSaveReadBlobDataResult](/ko/reference/system/xgamesave/functions/xgamesavereadblobdataresult.md)