您對數據存儲的請求可能會因為連接不良或其他問題而失敗。要處理錯誤並返回帶有錯誤代碼的消息，請將數據存儲函數包裹在 pcall() 中。
失敗的寫入調用，例如 UpdateAsync()，意味著遊戲伺服器未收到成功的響應。這並不總是保證後端寫入未發生。在某些故障情況下，最終寫入狀態可能會對調用者未知，直到使用後續的無緩存讀取進行驗證。
錯誤代碼參考
| 錯誤代碼 | 錯誤名稱 | 錯誤消息 | 備註 | |
|---|---|---|---|---|
| 101 | KeyNameEmpty | 鍵名不能為空。 | 檢查輸入到數據存儲函數的鍵是否為空字符串。 | |
| 102 | KeyNameLimit | 鍵名超過 50 個字符的限制。 | 檢查輸入到數據存儲函數的鍵是否超過 50 的長度。 | |
| 103 | ValueNotAllowed | 不能在 DataStore 中允許 X。 | 一個錯誤的更新函數返回的值的類型為 X。 | |
| 104 | CantStoreValue | 不能在 DataStore 中儲存 X。 | 更新函數返回的值的類型 X 無法序列化。 | |
| 105 | ValueTooLarge | 序列化的值超過 X 限制。 | 如果您使用 SetAsync() 或 UpdateAsync() 設置一個值，該值的序列化長度不能超過 X。要檢查數據的序列化長度，請使用 JSONEncode()。 | |
| 106 | MaxValueInvalid | MaxValue 必須是整數。 | 如果您向 GetSortedAsync() 傳遞最大值，它必須是整數。 | |
| 106 | MinValueInvalid | MinValue 必須是整數。 | 如果您向 GetSortedAsync() 傳遞最小值，它必須是整數。 | |
| 106 | PageSizeGreater | PageSize 必須在預定義範圍內。 | OrderedDataStore 的最小頁面大小為 1。 | |
| 106 | PageSizeLesser | PageSize 必須在預定義範圍內。 | OrderedDataStore 的最大頁面大小為 100。 | |
| 107 | MinMaxOrderInvalid | MaxValue 必須大於或等於 MinValue。 | 最大值必須大於或等於最小值，才能用於 GetSortedAsync()。 | |
| 301 | GetAsyncThrottle | GetAsync 請求已被丟棄。請求被限制但隊列已滿。 | GetAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 302 | SetAsyncThrottle | SetAsync 請求已被丟棄。請求被限制但隊列已滿。 | SetAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 303 | IncreAsyncThrottle | IncrementAsync 請求已被丟棄。請求被限制但隊列已滿。 | IncrementAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 304 | UpdateAsyncThrottle | UpdateAsync 請求已被丟棄。請求被限制但隊列已滿。 | UpdateAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 304 | TransformThrottle | UpdateAsync 請求已被丟棄。請求被限制但隊列已滿。 | UpdateAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 305 | GetSortedThrottle | GetSorted 請求已被丟棄。請求被限制但隊列已滿。 | GetSortedAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 306 | RemoveAsyncThrottle | RemoveAsync 請求已被丟棄。請求被限制但隊列已滿。 | RemoveAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | |
| 401 | DataModelNoAccess | 請求失敗。在經驗關閉時 DataModel 無法訪問。 | DataModel 未初始化，因為經驗正在關閉。 | |
| 402 | LuaWebSrvsNoAccess | 請求失敗。在經驗關閉時 LuaWebService 無法訪問。 | LuaWebService 未初始化，因為經驗正在關閉。 | |
| 403 | StudioAccessToApisNotAllowed | 因為未啟用 API 訪問，無法從 Studio 寫入 DataStore。 | 必須啟用 API 訪問才能在 Studio 中使用數據存儲。 | |
| 404 | InternalError | OrderedDataStore 不存在。 | 與此請求相關的 OrderedDataStore 未找到。這可能是數據損壞的跡象。請稍後再試。 | |
| 501 | InternalError | 無法解析響應，因為數據可能已損壞。 | 伺服器無法解析對您的請求的響應。這可能是數據損壞的跡象。請稍後再試。 | |
| 502 | RequestRejected | API 服務拒絕了錯誤 X 的請求。 | 處理 Roblox 伺服器時發生錯誤 X。請稍後再試。 | |
| 503 | InternalError | 數據存儲請求成功，但未找到鍵。 | 請求的鍵在數據存儲中未找到。這可能是數據損壞的跡象。請稍後再試。 | |
| 504 | InternalError | 數據存儲請求成功，但響應格式不正確。 | 伺服器無法解析對您的請求的響應。這可能是數據損壞的跡象。請稍後再試。 | |
| 505 | InternalError | OrderedDataStore 請求成功，但響應格式不正確。 | 伺服器無法解析對您的 OrderedDataStore 請求的響應。這可能是數據損壞的跡象。請稍後再試。 | |
| 509 | OperationNotAllowed | 為防止可能的數據損壞，在私人 RCC 上運行時阻止數據存儲操作。 | 在私人 RCC 通道上阻止數據存儲寫入。 | |
| 511 | AttributeSizeTooLarge | 元數據屬性大小超過 X 限制。 | 序列化的元數據大小超過 X 的限制。值 X 是動態的。如果大小發生變化，值也會變化。 | |
| 512 | UserIdLimitExceeded | UserID 大小超過 X 限制。 | 用戶提供的用戶 ID 陣列的長度超過 X 的限制。 | |
| 513 | AttributeFormatError | 屬性 userId 格式無效。 | 提供的用戶 ID 不是數字。 | |
| 513 | AttributeFormatError | 屬性元數據格式無效。 | 元數據不是一個表。 | |
| GetVersionAsyncThrottle | GetVersionAsync 請求已被丟棄。請求被限制。 | GetVersionAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | ||
| GetVersionAtTimeAsyncThrottle | GetVersionAtTimeAsync 請求已被丟棄。請求被限制。 | GetVersionAtTimeAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | ||
| ListDataStoresAsyncThrottle | ListDataStoresAsync 請求已被丟棄。請求被限制。 | ListDataStoresAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | ||
| ListKeysAsyncThrottle | ListKeysAsync 請求已被丟棄。請求被限制。 | ListKeysAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | ||
| ListVersionsAsyncThrottle | ListVersionsAsync 請求已被丟棄。請求被限制。 | ListVersionsAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | ||
| RemoveVersionAsyncThrottle | RemoveVersionAsync 請求已被丟棄。請求被限制。 | RemoveVersionAsync() 請求已超過最大隊列大小，Roblox 無法在當前吞吐量下處理請求。 | ||
| InvalidTimestamp | 時間戳必須是正數，並且不能超過未來的十分鐘。 | 提供的時間戳對於 GetVersionAtTimeAsync() 並不有效。 | ||
| StandardReadExperienceThrottled | StandardRead 請求因經驗限制而被限制。 | 對於標準數據存儲的請求 GetAsync()、GetVersionAsync()、GetVersionAtTimeAsync()、或 UpdateAsync() 超過了 StandardRead 經驗級別速率限制。 | ||
| StandardWriteExperienceThrottled | StandardWrite 請求因經驗限制而被限制。 | 對於標準數據存儲的請求 SetAsync()、IncrementAsync()、 或 UpdateAsync() 超過了 StandardWrite 經驗級別速率限制。 | ||
| StandardListExperienceThrottled | StandardList 請求因經驗限制而被限制。 | 對於標準數據存儲的請求 ListKeysAsync()、ListVersionsAsync()、或 ListDataStoresAsync() 超過了 StandardList 經驗級別速率限制。 | ||
| StandardRemoveExperienceThrottled | StandardRemove 請求因經驗限制而被限制。 | 對於標準數據存儲的請求 RemoveAsync() 超過了 StandardRemove 經驗級別速率限制。 | ||
| OrderedReadExperienceThrottled | OrderedRead 請求因經驗限制而被限制。 | 對於訂單數據存儲的請求 GetAsync() 或 UpdateAsync() 超過了 OrderedRead 經驗級別速率限制。 | ||
| OrderedWriteExperienceThrottled | OrderedWrite 請求因經驗限制而被限制。 | 對於訂單數據存儲的請求 SetAsync()、IncrementAsync()、或 UpdateAsync() 超過了 OrderedWrite 經驗級別速率限制。 | ||
| OrderedListExperienceThrottled | OrderedList 請求因經驗限制而被限制。 | 對訂單數據存儲的請求 GetSortedAsync() 超過了 OrderedList 經驗級別速率限制。 | ||
| OrderedRemoveExperienceThrottled | OrderedRemove 請求因經驗限制而被限制。 | 對於訂單數據存儲的請求 RemoveAsync() 超過了 OrderedRemove 經驗級別速率限制。 | ||
| StandardReadGameServerThrottled | StandardRead 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對標準數據存儲的請求 GetAsync()、GetVersionAsync()、GetVersionAtTimeAsync() 或 UpdateAsync() 超過了 StandardRead 遊戲伺服器級別速率限制。 | ||
| StandardWriteGameServerThrottled | StandardWrite 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對標準數據存儲的請求 SetAsync()、IncrementAsync() 或 UpdateAsync() 超過了 StandardWrite 遊戲伺服器級別速率限制。 | ||
| StandardListGameServerThrottled | StandardList 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對標準數據存儲的請求 ListKeysAsync()、ListVersionsAsync() 或 ListDataStoresAsync() 超過了 StandardList 遊戲伺服器級別速率限制。 | ||
| StandardRemoveGameServerThrottled | StandardRemove 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對於標準數據存儲的請求 RemoveAsync() 超過了 StandardRemove 遊戲伺服器級別速率限制。 | ||
| OrderedReadGameServerThrottled | OrderedRead 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對於訂單數據存儲的請求 GetAsync() 或 UpdateAsync() 超過了 OrderedRead 遊戲伺服器級別速率限制。 | ||
| OrderedWriteGameServerThrottled | OrderedWrite 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對於訂單數據存儲的請求 SetAsync()、IncrementAsync() 或 UpdateAsync() 超過了 OrderedWrite 遊戲伺服器級別速率限制。 | ||
| OrderedListGameServerThrottled | OrderedList 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對於訂單數據存儲的請求 GetSortedAsync() 超過了 OrderedList 遊戲伺服器級別速率限制。 | ||
| OrderedRemoveGameServerThrottled | OrderedRemove 請求因遊戲伺服器限制或請求隊列已滿而被限制。 | 對於訂單數據存儲的請求 RemoveAsync() 超過了 OrderedRemove 遊戲伺服器級別速率限制。 |
伺服器錯誤代碼
| 錯誤名稱 | 錯誤消息 | 備註 |
|---|---|---|
| DatastoreDeleted | 數據存儲已被刪除。 | 無法對數據存儲進行操作，因為該數據存儲已被刪除。 |
| DatastoreThrottled | 請求率超過了 datastore 的允許最大值。 | 對單個數據存儲發送了過多請求。 |
| InternalServerError | 發生了內部伺服器錯誤。 | Roblox 伺服器偶爾會出現錯誤。請重試，最好是使用指數回退。 |
| InvalidExclusiveStartKey | 提供的排他性起始鍵無效。 | 提供給列表操作（例如 ListKeysAsync()）的排他性起始鍵（光標）無效。 |
| InvalidPlace | 提供的地方無效。 | 沒有匹配該地方的宇宙 ID。請稍後重試。 |
| InvalidTarget | 提供的目標無效。 | 訂單數據存儲的鍵名超過 50 個字符的限制。 |
| InvalidUniverse | 提供的宇宙無效。 | 沒有匹配該宇宙的地方 ID。請稍後重試。 |
| InvalidUserIds | 所提供的用戶 ID 格式無效。 | 無法解析用戶 ID。 |
| KeyThrottled | 請求率超過鍵的允許最大值。 | 請求率超過單個鍵允許的最大請求率。 |
| KeyNotFound | 請求的鍵不存在。 | 該鍵不存在。 |
| N/A | 沒有可進一步處理的頁面。 | 當您在最後一頁上調用 Pages:AdvanceToNextPageAsync() 時會出現此錯誤。 |
| StandardReadExperienceThrottled | 標準讀取請求率超過了該經驗的允許最大值。 | 對於標準數據存儲的請求 GetAsync()、GetVersionAsync()、GetVersionAtTimeAsync() 或 UpdateAsync() 超過了 StandardRead 經驗級別速率限制。 |
| StandardWriteExperienceThrottled | 標準寫入請求率超過了該經驗的允許最大值。 | 對於標準數據存儲的請求 SetAsync()、IncrementAsync() 或 UpdateAsync() 超過了 StandardWrite 經驗級別速率限制。 |
| StandardListExperienceThrottled | 標準列表請求率超過了該經驗的允許最大值。 | 對於標準數據存儲的請求 ListKeysAsync()、ListVersionsAsync() 或 ListDataStoresAsync() 超過了 StandardList 經驗級別速率限制。 |
| StandardRemoveExperienceThrottled | 標準移除請求率超過了該經驗的允許最大值。 | 對於標準數據存儲的請求 RemoveAsync() 超過了 StandardRemove 經驗級別速率限制。 |
| OrderedReadExperienceThrottled | 訂單讀取請求率超過了該經驗的允許最大值。 | 對於訂單數據存儲的請求 GetAsync() 或 UpdateAsync() 超過了 OrderedRead 經驗級別速率限制。 |
| OrderedWriteExperienceThrottled | 訂單寫入請求率超過了該經驗的允許最大值。 | 對於訂單數據存儲的請求 SetAsync()、IncrementAsync() 或 UpdateAsync() 超過了 OrderedWrite 經驗級別速率限制。 |
| OrderedListExperienceThrottled | 訂單列表請求率超過了該經驗的允許最大值。 | 對於訂單數據存儲的請求 GetSortedAsync() 超過了 OrderedList 經驗級別速率限制。 |
| OrderedRemoveExperienceThrottled | 訂單移除請求率超過了該經驗的允許最大值。 | 對於訂單數據存儲的請求 RemoveAsync() 超過了 OrderedRemove 經驗級別速率限制。 |
限制
數據模型有 限制。如果經驗超過這些限制，服務將自動限制經驗的數據存儲使用，並使後續請求放入以下隊列之一：
- 設置
- 有序設置
- 獲取
- 有序獲取
隊列中的請求按接收順序處理。調用的函數將繼續暫停，只要其請求仍然在隊列中。如果數據存儲鍵本身被限制，請求將放入隊列中，但會被暫時跳過。
每個隊列有 30 個請求的限制。當達到隊列的限制時，請求將失敗並帶有 301-306 範圍的錯誤代碼，指示請求已被完全丟棄。
訪問限制
數據存儲受到 經驗和伺服器級別限制 的約束。經驗級別限制隨著經驗中的總並發用户數而變化，而伺服器級別限制是可配置的，旨在用作創建者的工具。
經驗限制
每個經驗根據數據存儲類型、請求類型和並發用戶數允許一定數量的數據存儲請求。對於每個數據存儲類型和請求類型，限制在所有列出的函數之間共享。
請注意，UpdateAsync() 同時消耗讀取和寫入請求預算。單個調用將減少這兩個限制。
標準數據存儲
| 請求類型 | 函數 | 每分鐘請求數 |
|---|---|---|
| 讀取 | GetAsync() GetVersionAsync() GetVersionAtTimeAsync() UpdateAsync() | 250 + 並發用戶數 × 40 |
| 寫入 | SetAsync() IncrementAsync() UpdateAsync() | 250 + 並發用戶數 × 20 |
| 列舉 | ListDataStoresAsync() ListKeysAsync() ListVersionsAsync() | 10 + 並發用戶數 × 2 |
| 刪除 | RemoveAsync() | 100 + 並發用戶數 × 40 |
有序數據存儲
| 請求類型 | 函數 | 每分鐘請求數 |
|---|---|---|
| 讀取 | GetAsync() UpdateAsync() | 250 + 並發用戶數 × 40 |
| 寫入 | SetAsync() IncrementAsync() UpdateAsync() | 250 + 並發用戶數 × 20 |
| 列舉 | GetSortedAsync() | 100 + 並發用戶數 × 2 |
| 刪除 | RemoveAsync() | 100 + 並發用戶數 × 40 |
伺服器限制
每個伺服器針對每個請求類型都有可配置的速率限制，根據該伺服器中的玩家人數而定。伺服器在創建時會接收到一次性啟動突發的額外請求預算。使用 GetRequestBudgetForRequestType() 來確認當前伺服器在任何時候可以發出的數據存儲請求數。
這些限制是由創建者 可配置的，通過 SetRateLimitForRequestType() API。創建者可以使用此API為每個請求類型配置自己的數據存儲速率限制。
如果未調用此 API，則適用以下 默認速率限制：
標準數據存儲
| 請求類型 | DataStoreRequestType 列舉 | 函數 | 每分鐘請求數 |
|---|---|---|---|
| 讀取 | StandardRead | GetAsync() GetVersionAsync() GetVersionAtTimeAsync() UpdateAsync() | 60 + 玩家數 × 40 |
| 寫入 | StandardWrite | SetAsync() IncrementAsync() UpdateAsync() | 60 + 玩家數 × 40 |
| 列舉 | StandardList | ListDataStoresAsync() ListKeysAsync() ListVersionsAsync() | 5 + 玩家數 × 2 |
| 刪除 | StandardRemove | RemoveAsync() | 60 + 玩家數 × 40 |
| RemoveVersion (已被棄用) | RemoveVersionAsync | RemoveVersionAsync() | 5 + 玩家數 × 2 |
有序數據存儲
| 請求類型 | DataStoreRequestType 列舉 | 函數 | 每分鐘請求數 |
|---|---|---|---|
| 讀取 | OrderedRead | GetAsync() UpdateAsync() | 60 + 玩家數 × 40 |
| 寫入 | OrderedWrite | SetAsync() IncrementAsync() UpdateAsync() | 30 + 玩家數 × 5 |
| 列舉 | OrderedList | GetSortedAsync() | 5 + 玩家數 × 2 |
| 刪除 | OrderedRemove | RemoveAsync() | 30 + 玩家數 × 5 |
在 Studio 運行模式下進行的數據存儲請求受一組單獨的靜態限制的約束，這些限制可能低於通過 SetRateLimitForRequestType() 配置的限制。在測試速率限制時，我們建議使用 Studio 團隊創建。
數據限制
數據存儲限制每條記錄可以使用的數據量。
數據存儲名稱、鍵名和 範圍 都必須在一定的字符長度之下。使用 string.len() 檢查它們的長度。
數據（鍵值）也作為字符串存儲，不論最初類型如何。您可以使用 JSONEncode() 函數檢查數據的大小，該函數將 Luau 數據轉換為序列化的 JSON 表。
| 組件 | 最大字符數 |
|---|---|
| 數據存儲名稱 | 50 |
| 鍵名 | 50 |
| 範圍 | 50 |
| 數據（鍵值） | 每個鍵 4,194,304 |
元數據限制
用戶自定義元數據的字符數量限制。
| 組件 | 最大字符數 |
|---|---|
| 鍵名 | 50 |
| 值 | 250 |
| 鍵值對 | 300 |
鍵值對的總數量沒有限制，但總大小不能超過 300 個字符。
吞吐量限制
每個鍵的吞吐量限制確保 Roblox 伺服器上的性能最佳。每個限制適用於經驗中所有伺服器上的每個鍵，並隨時間刷新。
Roblox 檢查與該鍵相關的配額在過去 60 秒內的使用情況。如果使用量，包括當前請求，仍在吞吐量限制內，則請求將被批准。如果使用量超過該限制，請求將被拒絕。
| 請求類型 | 限制 |
|---|---|
| 讀取 | 每分鐘 25 MB |
| 寫入 | 每分鐘 4 MB |
除了上述吞吐量限制外，Roblox 根據內部模式組織數據。結果，當後端伺服器收到對同一數據存儲的大量請求時，可能會導致進一步的限制。無論原因如何，限制的結果都是出現 DatastoreThrottled 或 KeyThrottled 錯誤，具體取決於單個數據存儲或鍵的吞吐量限制是否已超過。這些錯誤消息適用於有序和標準數據存儲。
對於每個請求，Roblox 將吞吐量上捲至下個千字節。例如，如果您寫入 800 個字節和 1.2 KB 的兩個請求，Roblox 將總計計算為 3 KB 的吞吐量（分別為 1 KB 和 2 KB）。
儲存限制
未來，為了提供可擴展且穩定的儲存體驗，數據存儲將實施經驗級別的儲存限制，以計算您的儲存使用量。
此限制將是每個經驗的基礎限制和根據您的經驗中的終身用戶數的每用戶限制的總和。終身用戶是任何至少加入過您經驗一次的用戶。
儲存限制的計算公式為 Total latest version storage limit = 100 MB + 1 MB * lifetime user count。
任何您刪除或替換的鍵，即使仍可通過版本 API 訪問，也不會計入您的經驗的儲存使用量。然而，通過 Open Cloud DeleteDataStore 方法刪除的整個數據存儲在 30 天的處理期內仍然會計入您的儲存使用量，直到它們被永久刪除。