> ## 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 匹配的一般流程。有关更多信息,请参阅我们的[匹配快速入门](/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 匹配会根据 Game Manager 中配置的限制来限制你所进行的调用数量。收到 `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 返回未找到

对局创建后,对局会存在一段时间并最终失效。如果没有及时检索对局,这些用户需要重新提交工单才能再次匹配。可以通过确保及时检索对局(即在几分钟内)来避免这种情况。

如果你按此处所述将 [Matchmaking 与 Lobby 一同使用](/services/playfab/multiplayer/lobby/lobby-and-matchmaking),则在对局在此处超时之后,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-CN/services/playfab/multiplayer/matchmaking/index.md)
- [市场错误处理](/zh-CN/services/playfab/economy-monetization/economy-v2/marketplace/marketplace-error-handling.md)
- [PlayFab Party 错误代码](/zh-CN/services/playfab/multiplayer/networking/reference/partyerrors.md)
- [游戏存档概述](/zh-CN/build/core-features/common/game-save/game-saves-overview.md)
- [游戏存档调试](/zh-CN/build/core-features/common/game-save/game-saves-debugging.md)