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

# 全局 API 方法错误代码

> 列出适用于每个 PlayFab API 方法的全局错误代码。

本教程列出了适用于每个 PlayFab API 方法的全局错误代码。以下信息可用于解读 API 错误。

每个 API 错误包含以下字段：

* **Code** - 服务器返回的 HTTP 错误代码
* **ErrorCode** - PlayFab 特定的数字错误代码。
* **Error** - PlayFab 特定的、便于阅读的代码。
* **ErrorMessage** - 错误的描述，为调试提供额外的有用上下文。
* **ErrorDetails** - 并非始终存在。为某些类型的错误提供额外的上下文。

<Note>
  本页列出了您可能会遇到的常见错误代码。如果您要查找的错误代码在本页中不可用，请参阅我们更通用的 [HTTP 响应状态代码指南](/services/playfab/api-references/http-response-status-codes)。
</Note>

## 可安全重试的代码

对于以这些错误代码失败的请求，通常可以安全地进行重试，并采用指数退避延迟。这些错误通常意味着您的客户端调用过快，但请求本身可能是有效的。

* `APIClientRequestRateLimitExceeded (1199)`：表示在短时间内调用次数过多。
* `APIConcurrentRequestLimitExceeded (1342)`：表示\_同时\_发生的调用次数过多。
* `ConcurrentEditError (1133)`：表示\_同时\_发生的调用过多或\_连续\_调用过于快速。
* `DataUpdateRateExceeded (1287)`：表示\_同时发生的调用\_过多，或\_连续\_调用过于快速。
* `DownstreamServiceUnavailable (1127)`：表示 PlayFab 或第三方服务可能存在暂时性问题。
* `ServiceUnavailable (1123)`：表示 PlayFab 可能存在暂时性问题，或客户端 API 调用过于频繁。如果您重试此请求，正确地使用指数退避策略非常重要。

## 切勿重试的代码

如果您收到这些错误代码，则\_切勿\_重试，因为在没有修复错误或更改设置的情况下，请求永远无法在当前情况下完成。

大多数在 API 方法中列出的\_特定\_代码也属于此类。

* `AccountBanned (1002)`：<br />玩家账户已被封禁，所有 API 方法都将因此错误而失败。
* `AccountDeleted (1322)`：玩家账户已被删除，所有 API 方法都将因此错误而失败。
* `AccountNotFound (1001)`：玩家账户不存在，可能是因为您未正确复制 `PlayFabId/TitlePlayerId`。如果标识符不正确，将始终发生此错误。
* `APIRequestsDisabledForTitle (1295)`：此游戏的所有 API 请求均已被禁用，且不能再使用。
* `InvalidContentType (1144)`：如果您正在使用我们的 SDK 之一，则不应遇到此错误。如果您对 PlayFab API 方法进行自己的原始 HTTPS 调用，您的 `Content-Type` 标头必须为 `application/json`。不接受其他格式。
* `InvalidEntityType (1373)`：用于身份验证的令牌中的实体类型不受此 API 支持。
* `InvalidParams (1000)`：发送到 PlayFab 的 API 请求对象包含无效参数，无法执行。
* `InvalidRequest (1071)`：发送到 PlayFab 的 API 请求对象无效，无法执行。
* `InvalidTitleId (1004)`：请求提供了一个 TitleId，它与方法 URL 中提供的游戏\_不\_匹配。在大多数 SDK 中，您不应为登录请求指定 TitleId，因为它会自动为您处理。在管理 API 中，显式的 TitleId 是一项 **Dev**->**Test**->**Live** 的安全功能。
* `NotAuthenticated (1074)`：客户端在未先登录的情况下尝试调用需要 `SessionTicket` 身份验证的 API。
* `NotAuthorized (1089)`：凭据不正确，或与登录相关的其他错误输入。
* `NotAuthorizedByTitle (1191)`：此方法已被 API 策略禁用，无法调用。
* `ProfileDoesNotExist (1298)`：尝试访问一个不存在的实体（玩家、角色、游戏等）。可能是拼写错误，或者您在某处输入了错误的内容。
* `TitleDeleted (1347)`：此游戏已从 PlayFab 中删除，无法再使用。
* `UnknownError (1039)`：这通常发生在向第三方附加组件发送了错误信息，并且我们的服务器在与外部系统交互时遇到未知的结果或错误。要解决此问题，请尝试更改您的输入，并尝试确定您的输入是否以某种方式无效。否则，请在论坛上报告该错误，附上您的 titleId、完整的请求 JSON（如果可能）以及错误输出。Postman 是调试此类情况的有用工具。
* `InvalidAPIEndpoint (1131)`：表示此请求的 URL 对此游戏无效。
* `OverLimit (1214)`：表示尝试执行某项操作会导致服务使用量超过 Game Manager 限制页面中所示的限制。评估返回的错误详细信息以确定将超过哪个限制。

## 其他值得注意的错误代码

这些代码\_仅\_发生在特定的 API 方法上（列在这些方法的文档页面上），但如果您看到它们，需要注意一些重要的后果。

* `APIConcurrentRequestLimitExceeded (1342)`：您的游戏要么对 CloudScript 的调用过于频繁，要么在过于频繁地尝试强制进行细分评估（或两者兼有）。对于前者，需要检查两点：
  1. 您的脚本调用有多频繁地占用接近最大时间（或更糟糕的是，超时）。
  2. 每个玩家调用 CloudScript 的频率。要重点检查的是获取某个细分中的玩家列表的调用（针对某个细分的任务也会导致重新评估，但这种情况应该很少）。
* `ConnectionTimeout (2)`：根据您使用的 SDK 的具体情况以及底层网络堆栈，您可能会看到诸如 **ConnectionError**、**ConnectionTimeout** 或其他与联系 PlayFab 服务器困难相关的错误。这些都表明存在网络问题。最常见的原因是客户端断开连接。当客户端与 PlayFab 服务器之间的互联网路由因某种原因中断时，也可能出现这些错误。游戏能做的处理非常有限。最好的响应是让上游调用方或玩家知道无法建立连接。他们随后可以稍后再次发起该操作。


## Related topics

- [SDK 错误处理最佳实践](/zh-CN/services/playfab/live-service-management/service-gateway/automation/cloudscript/sdk-error-handling-best-practices.md)
- [在 CloudScript 中处理错误](/zh-CN/services/playfab/live-service-management/service-gateway/automation/cloudscript/handling-errors-in-cloudscript.md)
- [适用于原生 JavaScript 和 Phaser 的 JavaScript 快速入门](/zh-CN/services/playfab/sdks/javascript/quickstart.md)
- [NodeJS 快速入门](/zh-CN/services/playfab/sdks/nodejs/quickstart.md)
- [处理 PlayFab 错误](/zh-CN/services/playfab/sdks/c/errors.md)