> ## 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 Matchmaking 錯誤案例，包括票證取消、逾時、無效屬性和比賽建立失敗。

PlayFab 配對提供簡單的介面來進入和離開配對。儘管如此，仍有多個環節*可能*不會照計畫進行。以下列出一些較常見的錯誤案例，以及遊戲應如何處理。

本頁假設您已熟悉 PlayFab 配對的一般流程。如需配對常見用法的詳細資訊，請參閱我們的[配對快速入門](/zh-TW/services/playfab/multiplayer/matchmaking/quickstart)。

## 建立票證時的錯誤

建立票證可能因許多原因而失敗。在大多數情況下，PlayFab 錯誤碼會指出提交要求中的無效之處。修正之後，您就能成功提交。

<Note>
  錯誤 `MatchmakingAttributeInvalid` 和 `MatchmakingPlayerAttributesInvalid` 表示屬性格式有問題。如需如何在票證中傳遞屬性的詳細資訊，請參閱[指定票證屬性](/zh-TW/services/playfab/multiplayer/matchmaking/ticket-attributes)一節。
</Note>

其他錯誤碼表示要求有效，但要求以外的情況導致票證無法被接受。具體來說，這些錯誤碼包括：

1. `MatchmakingRateLimitExceeded` - 這表示您提交票證的頻率太高。如需詳細資訊，請參閱[下方](#call-returns-matchmakingratelimitexceeded)一節。
2. `MatchmakingTicketMembershipLimitExceeded` - 這表示使用者已在另一張作用中的票證中。使用者在同一個佇列中一次只能位於一張票證中，因為他們無法同時玩兩場遊戲。如需修正此情況的詳細資訊，請參閱[下方](#creating-or-joining-a-ticket-returns-matchmakingticketmembershiplimitexceeded)更詳細的章節。

如果您收到 HTTP 錯誤碼 503，請在短暫延遲後重試要求。

<a id="call-returns-matchmakingratelimitexceeded" />

## 呼叫傳回 MatchmakingRateLimitExceeded

與其他 PlayFab 功能類似，PlayFab 配對會根據 Game Manager 內設定的限制，限制您進行的呼叫次數。收到 `MatchmakingRateLimitExceeded` 錯誤表示遊戲已超過此呼叫類型的限制。

在配對中，這最常發生在輪詢 [GetMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket) 以查看票證是否已配對時。

若要避免此錯誤，請提高您的限制，或降低呼叫頻率。

<Note>
  雖然回應的 HTTP 狀態碼為 429，但要求本身是有效的，仍可重試。
</Note>

<a id="creating-or-joining-a-ticket-returns-matchmakingticketmembershiplimitexceeded" />

## 建立或加入票證時傳回 MatchmakingTicketMembershipLimitExceeded

在 PlayFab 配對中，使用者在每個佇列中一次只能位於一張票證中，以避免使用者進入兩場比賽，而必須決定要履行哪張票證的情況。未被履行的比賽會少一位玩家，其玩家很可能被迫重新進入配對。如果使用者已位於一張尚未取消或配對的票證中，卻嘗試建立或加入另一張票證，就會傳回錯誤 `MatchmakingTicketMembershipLimitExceeded`。

不過，有時遊戲或伺服器可能會因為當機、重新啟動或其他無法預期的錯誤而失去票證的追蹤。發生這種情況時，就會留下一張使用者和遊戲都不知道的作用中票證。

這張遺失的票證會阻止為此使用者提交任何未來的票證，直到其到期為止。如果發生這種情況，有兩個選項可以解決此問題：

### 選項 1：從配對中清除票證

取消使用者所有現有的票證。呼叫 [CancelAllMatchmakingTicketsForPlayer](xref:titleid.playfabapi.com.multiplayer.matchmaking.cancelallmatchmakingticketsforplayer) 即可執行此工作。之後，配對中不會有任何進行中的票證，並準備好建立新的票證。

### 選項 2：找出遺失的票證

找出使用者現有的票證並繼續使用。呼叫 [ListMatchmakingTicketsForPlayer](xref:titleid.playfabapi.com.multiplayer.matchmaking.listmatchmakingticketsforplayer) 會傳回使用者所屬的所有配對票證識別碼。對每個提供的 ticketId 呼叫 [GetMatchmakingTicket](xref:titleid.playfabapi.com.multiplayer.matchmaking.getmatchmakingticket)，即可擷取其狀態並持續監視，直到找到比賽為止。

## 並非所有玩家都加入多使用者票證

建立多使用者票證時，其中一位受邀玩家可能無法加入或拒絕加入。在這種情況下，建立的票證會維持在 WaitingForPlayers 狀態，直到到期為止。遊戲應預期這種情況偶爾會發生，並在 UI 中設定相當短的逾時。

逾時之後，遊戲應取消票證，並確認所有玩家仍同意一起玩遊戲。

## GetMatch 傳回找不到

比賽建立後會存在一段時間，最終會過期。如果未及時擷取比賽，這些使用者需要重新提交票證才能再次配對。確保及時 (也就是在幾分鐘內) 擷取比賽即可避免這種情況。

如果您依照[這裡](/zh-TW/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

- [配對](/zh-TW/services/playfab/multiplayer/matchmaking/index.md)
- [Game Saves 錯誤處理常見問題集](/zh-TW/services/playfab/player-progression/game-saves/error-handling-faq.md)
- [Game Saves 概觀](/zh-TW/build/core-features/common/game-save/game-saves-overview.md)
- [市集錯誤處理](/zh-TW/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-error-handling.md)
- [Game Saves 系統對話方塊](/zh-TW/build/core-features/common/game-save/game-saves-dialogues.md)