通过

全局 API 方法错误代码

  • 项目

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

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

  • 代码 - 服务器返回的 HTTP 错误代码
  • ErrorCode - 特定于 PlayFab 的数字错误代码。
  • 错误 - 特定于 PlayFab 的可读代码。
  • ErrorMessage - 为调试提供其他有用上下文的错误说明。
  • ErrorDetails - 并非始终存在。 为某些类型的错误提供其他上下文。

注意

此页列出了你可能会遇到的常见错误代码。 如果要查找的错误代码在此页上不可用，请参阅我们更常规的 http 响应状态代码指南。

重试安全代码

对失败时带这些错误代码的请求进行重试通常是安全的，采用指数延迟等待。 这些错误通常意味着客户端调用过快，但请求本身是有效的。

  • APIClientRequestRateLimitExceeded (1199)：指示短暂突发中的调用过多。

  • APIConcurrentRequestLimitExceeded (1342)：表示同时进行的调用过多。

  • ConcurrentEditError (1133): 表示同时进行的调用过多，或顺序调用过快。

  • DataUpdateRateExceeded (1287)： 表示同时进行的调用过多，或顺序调用过快。

  • DownstreamServiceUnavailable (1127)：指示 PlayFab 或第三方服务可能存在临时问题。

  • ServiceUnavailable (1123)：指示 PlayFab 可能存在暂时性问题，或者客户端发出的 API 调用过多。 如果重试此请求，请务必正确使用指数退避策略。

切勿重试代码

如果收到这种错误代码，切勿 重试，这是因为在当前环境没有修复 Bug 或更改设置的情况下，该请求是无法完成的。

API 方法所列的大多数特定 代码也属于此类。

  • AccountBanned (1002):
    玩家帐户已被禁用，所有 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 是开发->测试->动态安全功能。

  • 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 的服务器之间的 Internet 路由因某种原因中断时，也可以获取这些信息。 游戏几乎无法处理这些错误。 最佳响应是让上游调用方或玩家知道无法建立连接。 然后，他们可以稍后再次启动该操作。