> ## 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 回應狀態碼指引](/zh-TW/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-TW/services/playfab/live-service-management/service-gateway/automation/cloudscript/sdk-error-handling-best-practices.md)
- [處理 CloudScript 中的錯誤](/zh-TW/services/playfab/live-service-management/service-gateway/automation/cloudscript/handling-errors-in-cloudscript.md)
- [適用於原生與 Phaser 的 JavaScript 快速入門](/zh-TW/services/playfab/sdks/javascript/quickstart.md)
- [NodeJS 快速入門](/zh-TW/services/playfab/sdks/nodejs/quickstart.md)
- [處理 PlayFab 錯誤](/zh-TW/services/playfab/sdks/c/errors.md)