數據存儲錯誤代碼和限制

*此內容是使用 AI(Beta 測試版)翻譯,可能含有錯誤。若要以英文檢視此頁面,請按一下這裡

您對數據存儲的請求可能因為連接不良或其他問題而失敗。要處理錯誤並返回帶有錯誤代碼的消息,請將數據存儲函數包裝在 pcall() 中。

失敗的寫入調用,例如 UpdateAsync(),意味著遊戲伺服器未收到成功的響應。這並不總是保證後端寫入未發生。在某些失敗場景中,最終的寫入狀態可能在後續未緩存的讀取驗證之前對調用者未知。

錯誤代碼參考

錯誤代碼錯誤名稱錯誤消息備註
101KeyNameEmpty鍵名不能為空。檢查輸入到數據存儲函數的鍵是否為空字符串。
102KeyNameLimit鍵名超過 50 個字符的限制。檢查輸入到數據存儲函數的鍵是否超過 50 的長度。
103ValueNotAllowed不能在 DataStore 中允許 X一個錯誤的更新函數返回了類型 X 的值。
104CantStoreValue不能在 DataStore 中存儲 X更新函數返回了一個類型 X 的值,該值無法序列化。
105ValueTooLarge序列化的值超過 X 限制。如果您使用 SetAsync()UpdateAsync() 設置值,則該值的序列化長度不能超過大小 X。要檢查數據的序列化長度,請使用 JSONEncode()
106MaxValueInvalidMaxValue 必須是整數。如果您將最大值傳遞給 GetSortedAsync(),則它必須是整數。
106MinValueInvalidMinValue 必須是整數。如果您將最小值傳遞給 GetSortedAsync(),則它必須是整數。
106PageSizeGreaterPageSize 必須在預定義範圍內。對於 OrderedDataStore,最小頁面大小為 1。
106PageSizeLesserPageSize 必須在預定義範圍內。對於 OrderedDataStore,最大頁面大小為 100。
107MinMaxOrderInvalidMaxValue 必須大於或等於 MinValue對於 GetSortedAsync(),最大值必須大於或等於最小值。
301GetAsyncThrottleGetAsync 請求被丟棄。請求被限制,但隊列已滿。GetAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
302SetAsyncThrottleSetAsync 請求被丟棄。請求被限制,但隊列已滿。SetAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
303IncreAsyncThrottleIncrementAsync 請求被丟棄。請求被限制,但隊列已滿。IncrementAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
304UpdateAsyncThrottleUpdateAsync 請求被丟棄。請求被限制,但隊列已滿。UpdateAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
304TransformThrottleUpdateAsync 請求被丟棄。請求被限制,但隊列已滿。UpdateAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
305GetSortedThrottleGetSorted 請求被丟棄。請求被限制,但隊列已滿。GetSortedAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
306RemoveAsyncThrottleRemoveAsync 請求被丟棄。請求被限制,但隊列已滿。RemoveAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
401DataModelNoAccess請求失敗。當體驗關閉時,DataModel 無法訪問。DataModel 未初始化,因為體驗正在關閉。
402LuaWebSrvsNoAccess請求失敗。當體驗關閉時,LuaWebService 無法訪問。LuaWebService 未初始化,因為體驗正在關閉。
403StudioAccessToApisNotAllowed因為未啟用 API 訪問,無法從 Studio 寫入 DataStore必須啟用 API 訪問才能在 Studio 中使用數據存儲。
404InternalErrorOrderedDataStore 不存在。與此請求相關的 OrderedDataStore 未找到。這可能是數據損壞的跡象。請稍後再試。
501InternalError無法解析響應,因為數據可能已損壞。伺服器無法解析對您的請求的響應。這可能是數據損壞的跡象。請稍後再試。
502RequestRejectedAPI 服務拒絕了請求,錯誤 X在 Roblox 伺服器上處理時發生錯誤 X。請稍後再試。
503InternalError數據存儲請求成功,但未找到鍵。請求的鍵在數據存儲中未找到。這可能是數據損壞的跡象。請稍後再試。
504InternalError數據存儲請求成功,但響應格式不正確。伺服器無法解析對您的請求的響應。這可能是數據損壞的跡象。請稍後再試。
505InternalErrorOrderedDataStore 請求成功,但響應格式不正確。伺服器無法解析對您的 OrderedDataStore 請求的響應。這可能是數據損壞的跡象。請稍後再試。
509OperationNotAllowed在個人 RCC 上運行時,數據存儲操作被阻止,以防止可能的數據損壞。在私有 RCC 通道上阻止數據存儲寫入。
511AttributeSizeTooLarge元數據屬性大小超過 X 限制。序列化的元數據大小超過 X 的限制。值 X 是動態的。如果大小變化,該值也會變化。
512UserIdLimitExceededUserID 大小超過 X 限制。用戶提供的用戶 ID 陣列的長度超過 X 的限制。
513AttributeFormatError屬性 userId 格式無效。提供的用戶 ID 不是數字。
513AttributeFormatError屬性元數據格式無效。元數據不是表。
GetVersionAsyncThrottleGetVersionAsync 請求被丟棄。請求被限制。GetVersionAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
GetVersionAtTimeAsyncThrottleGetVersionAtTimeAsync 請求被丟棄。請求被限制。GetVersionAtTimeAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
ListDataStoresAsyncThrottleListDataStoresAsync 請求被丟棄。請求被限制。ListDataStoresAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
ListKeysAsyncThrottleListKeysAsync 請求被丟棄。請求被限制。ListKeysAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
ListVersionsAsyncThrottleListVersionsAsync 請求被丟棄。請求被限制。ListVersionsAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
RemoveVersionAsyncThrottleRemoveVersionAsync 請求被丟棄。請求被限制。RemoveVersionAsync() 請求已超過最大隊列大小,Roblox 無法以當前吞吐量處理請求。
InvalidTimestamp時間戳必須是正數,且不超過十分鐘的未來。提供給 GetVersionAtTimeAsync() 的時間戳無效。
StandardReadExperienceThrottledStandardRead 請求因體驗限制而被限制。GetAsync()GetVersionAsync()GetVersionAtTimeAsync() 或標準數據存儲上的 UpdateAsync() 的請求超過了 StandardRead 體驗級別速率限制。
StandardWriteExperienceThrottledStandardWrite 請求因體驗限制而被限制。SetAsync()IncrementAsync() 或標準數據存儲上的 UpdateAsync() 的請求超過了 StandardWrite 體驗級別速率限制。
StandardListExperienceThrottledStandardList 請求因體驗限制而被限制。對標準數據存儲上的 ListKeysAsync()ListVersionsAsync()ListDataStoresAsync() 的請求超過了 StandardList 體驗級別速率限制。
StandardRemoveExperienceThrottledStandardRemove 請求因體驗限制而被限制。對標準數據存儲上的 RemoveAsync() 的請求超過了 StandardRemove 體驗級別速率限制。
OrderedReadExperienceThrottledOrderedRead 請求因體驗限制而被限制。GetAsync()BatchGetAsync() 或有序數據存儲上的 UpdateAsync() 的請求超過了 OrderedRead 體驗級別速率限制。
OrderedWriteExperienceThrottledOrderedWrite 請求因體驗限制而被限制。SetAsync()IncrementAsync() 或有序數據存儲上的 UpdateAsync() 的請求超過了 OrderedWrite 體驗級別速率限制。
OrderedListExperienceThrottledOrderedList 請求因體驗限制而被限制。對有序數據存儲上的 GetSortedAsync() 的請求超過了 OrderedList 體驗級別速率限制。
OrderedRemoveExperienceThrottledOrderedRemove 請求因體驗限制而被限制。對有序數據存儲上的 RemoveAsync() 的請求超過了 OrderedRemove 體驗級別速率限制。
StandardReadGameServerThrottledStandardRead 請求因遊戲伺服器限制或請求隊列已滿而被限制。GetAsync()GetVersionAsync()GetVersionAtTimeAsync() 或標準數據存儲上的 UpdateAsync() 的請求超過了 StandardRead 遊戲伺服器級別速率限制。
StandardWriteGameServerThrottledStandardWrite 請求因遊戲伺服器限制或請求隊列已滿而被限制。SetAsync()IncrementAsync() 或標準數據存儲上的 UpdateAsync() 的請求超過了 StandardWrite 遊戲伺服器級別速率限制。
StandardListGameServerThrottledStandardList 請求因遊戲伺服器限制或請求隊列已滿而被限制。ListKeysAsync()ListVersionsAsync()ListDataStoresAsync() 的請求超過了 StandardList 遊戲伺服器級別速率限制。
StandardRemoveGameServerThrottledStandardRemove 請求因遊戲伺服器限制或請求隊列已滿而被限制。對標準數據存儲上的 RemoveAsync() 的請求超過了 StandardRemove 遊戲伺服器級別速率限制。
OrderedReadGameServerThrottledOrderedRead 請求因遊戲伺服器限制或請求隊列已滿而被限制。GetAsync()BatchGetAsync() 或有序數據存儲上的 UpdateAsync() 的請求超過了 OrderedRead 遊戲伺服器級別速率限制。
OrderedWriteGameServerThrottledOrderedWrite 請求因遊戲伺服器限制或請求隊列已滿而被限制。SetAsync()IncrementAsync() 或有序數據存儲上的 UpdateAsync() 的請求超過了 OrderedWrite 遊戲伺服器級別速率限制。
OrderedListGameServerThrottledOrderedList 請求因遊戲伺服器限制或請求隊列已滿而被限制。對有序數據存儲上的 GetSortedAsync() 的請求超過了 OrderedList 遊戲伺服器級別速率限制。
OrderedRemoveGameServerThrottledOrderedRemove 請求因遊戲伺服器限制或請求隊列已滿而被限制。對有序數據存儲上的 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()BatchGetAsync() 或有序數據存儲上的 UpdateAsync() 的請求超過了 OrderedRead 體驗級別速率限制。
OrderedWriteExperienceThrottled有序寫入請求速率超過體驗的允許最大值。SetAsync()IncrementAsync() 或有序數據存儲上的 UpdateAsync() 的請求超過了 OrderedWrite 體驗級別速率限制。
OrderedListExperienceThrottled有序列表請求速率超過體驗的允許最大值。對有序數據存儲上的 GetSortedAsync() 的請求超過了 OrderedList 體驗級別速率限制。
OrderedRemoveExperienceThrottled有序刪除請求速率超過體驗的允許最大值。對有序數據存儲上的 RemoveAsync() 的請求超過了 OrderedRemove 體驗級別速率限制。

限制

數據模型有 限制。如果體驗超過這些限制,服務會自動限制體驗的數據存儲使用,並使未來的請求放入以下隊列之一:

  • 設置
  • 有序設置
  • 獲取
  • 有序獲取

隊列中的請求按接收順序處理。調用的函數在請求仍在隊列中時會繼續讓步。如果數據存儲鍵本身被限制,請求將被放入隊列,但會暫時跳過。

每個隊列的請求限制為 30 個請求。當隊列的限制達到時,請求將以 301-306 範圍內的錯誤代碼失敗,表示請求已完全丟棄。

訪問限制

數據存儲受 體驗和伺服器級別限制 的約束。體驗級別限制隨著體驗中的總並發用戶數而變化,而伺服器級別限制是可配置的,旨在作為創作者的工具。

體驗限制

每個體驗根據數據存儲類型、請求類型和並發用戶數允許一定數量的數據存儲請求。對於每種類型的數據存儲和請求類型,限制在所有列出的函數之間共享。

  • UpdateAsync() 同時消耗讀取和寫入請求預算。單個調用將減少兩個限制。
  • 遊戲伺服器和開放雲 共享 預算;開放雲流量可能會受到體驗內使用的限制(反之亦然)。有關進一步指導,請參見 控制速率限制
標準數據存儲
請求類型遊戲伺服器 API開放雲 API共享限制(每分鐘請求數)
讀取GetAsync()
GetVersionAsync()
GetVersionAtTimeAsync()
UpdateAsync()
獲取數據存儲條目300 + concurrentUsers × 40
寫入SetAsync()
IncrementAsync()
UpdateAsync()
創建、更新、增量數據存儲條目300 + concurrentUsers × 20
列表ListDataStoresAsync()
ListKeysAsync()
ListVersionsAsync()
列出數據存儲、列出數據存儲條目、列出數據存儲條目修訂版300 + concurrentUsers × 2
刪除RemoveAsync()刪除數據存儲條目、刪除數據存儲、恢復數據存儲300 + concurrentUsers × 40
有序數據存儲
請求類型遊戲伺服器 API開放雲 API共享限制(每分鐘請求數)
讀取GetAsync()
BatchGetAsync()
UpdateAsync()
獲取有序數據存儲條目300 + concurrentUsers × 40
寫入SetAsync()
IncrementAsync()
UpdateAsync()
創建、更新、增量有序數據存儲條目300 + concurrentUsers × 20
列表GetSortedAsync()列出有序數據存儲條目300 + concurrentUsers × 2
刪除RemoveAsync()刪除有序數據存儲條目300 + concurrentUsers × 40
控制速率限制

由於開放雲和遊戲伺服器請求是共享的,因此獨立控制每個請求類型的消耗量非常重要。

遊戲伺服器

單個伺服器具有內置限制,如上所述。使用 SetRateLimitForRequestType()GetRequestBudgetForRequestType() 的組合來維持對單個伺服器對總預算貢獻的精細控制。

開放雲

開放雲請求需要外部速率限制解決方案。我們建議以下方法之一:

  • (簡單)在每個請求後添加短暫的超時,特別是如果在連續循環中調用相同的 API。將此超時設置為 60 / (每分鐘所需的預算消耗) 秒,作為上限。請注意,這種方法不允許請求以突發方式發送。
  • (穩健)使用漏桶策略實現本地速率限制器。

以下 Node.js 代碼示例包括參考實現。

const apiKey = process.env.API_KEY;
if (!apiKey) {
throw new Error('The API_KEY environment variable is not set.');
}
const apiHeaderKey = 'x-api-key';
const universeId = '';
const dataStoreId = 'Inventory';
const baseUrl = 'https://apis.roblox.com/cloud/v2/';
// --- 每操作的速率限制配置(每分鐘請求數) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;
// 每操作的上限間隔:60 / (每分鐘請求數) 秒。
const LIST_INTERVAL_MS = (60 / LIST_RATE_PER_MIN) * 1000;
const GET_INTERVAL_MS = (60 / GET_RATE_PER_MIN) * 1000;
const UPDATE_INTERVAL_MS = (60 / UPDATE_RATE_PER_MIN) * 1000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// 執行請求,然後在返回之前等待此操作的間隔。
async function throttledFetch(url, options, intervalMs) {
const response = await fetch(url, options);
await sleep(intervalMs);
return response;
}
async function listEntries(universe, dataStore) {
const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
const url = baseUrl + listPath;
const response = await throttledFetch(url, {
headers: { [apiHeaderKey]: apiKey }
}, LIST_INTERVAL_MS);
return response.json();
}
async function getEntry(path) {
const url = baseUrl + path;
const response = await throttledFetch(url, {
headers: { [apiHeaderKey]: apiKey }
}, GET_INTERVAL_MS);
return response.json();
}
async function updateEntry(path, payload) {
const url = baseUrl + path;
const response = await throttledFetch(url, {
method: 'PATCH',
headers: {
[apiHeaderKey]: apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload) // 主體必須是字符串
}, UPDATE_INTERVAL_MS);
return response;
}
(async () => {
try {
const entries = await listEntries(universeId, dataStoreId);
for (const entry of entries.dataStoreEntries) {
const path = entry.path;
console.log(`\nProcessing entry: ${path}`);
const currentData = await getEntry(path);
currentData.value.currency += 10;
const payload = { value: currentData.value };
const updateResponse = await updateEntry(path, payload);
console.log(`Status: ${updateResponse.status}`);
console.log(`Response: ${await updateResponse.text()}`);
}
} catch (error) {
console.error('An error occurred during execution:', error);
}
})();

伺服器限制

每個伺服器對每種類型的請求都有可配置的速率限制,基於該伺服器中的玩家數量。伺服器在首次創建時會獲得一次性啟動突發的額外請求預算。使用 GetRequestBudgetForRequestType() 確認當前伺服器在任何給定時間可以發出的數據存儲請求數量。

這些限制是 可由創作者配置的,使用 SetRateLimitForRequestType() API。使用此 API,創作者可以為每種類型的請求配置自己的數據存儲速率限制。

如果未調用 API,則適用以下 默認速率限制

標準數據存儲
請求類型DataStoreRequestType 枚舉遊戲伺服器 API每分鐘請求數
讀取StandardReadGetAsync()
GetVersionAsync()
GetVersionAtTimeAsync()
UpdateAsync()
60 + numPlayers × 40
寫入StandardWriteSetAsync()
IncrementAsync()
UpdateAsync()
60 + numPlayers × 40
列表StandardListListDataStoresAsync()
ListKeysAsync()
ListVersionsAsync()
5 + numPlayers × 2
刪除StandardRemoveRemoveAsync()60 + numPlayers × 40
刪除版本(已棄用)RemoveVersionAsyncRemoveVersionAsync()5 + numPlayers × 2
有序數據存儲
請求類型DataStoreRequestType 枚舉遊戲伺服器 API每分鐘請求數
讀取OrderedReadGetAsync()
BatchGetAsync()
UpdateAsync()
60 + numPlayers × 40
寫入OrderedWriteSetAsync()
IncrementAsync()
UpdateAsync()
30 + numPlayers × 5
列表OrderedListGetSortedAsync()5 + numPlayers × 2
刪除OrderedRemoveRemoveAsync()30 + numPlayers × 5

數據限制

數據存儲限制每個條目可以使用的數據量。

數據存儲名稱、鍵名和 範圍 必須都在一定的字符長度之下。使用 string.len() 檢查它們的長度。

數據(鍵值)也作為字符串存儲,無論其初始類型如何。您可以使用 JSONEncode() 函數檢查數據的大小,該函數將 Luau 數據轉換為序列化的 JSON 表。

組件最大字符數
數據存儲名稱50
鍵名50
範圍50
數據(鍵值)每個鍵 4,194,304

元數據限制

用戶定義的元數據中的字符數限制。

組件最大字符數
鍵名50
250
鍵值對300

吞吐量限制

每個鍵的吞吐量限制確保 Roblox 伺服器上的性能最佳。每個限制適用於體驗中所有伺服器的每個鍵,並隨時間刷新。

Roblox 檢查與該鍵相關的配額使用情況,時間範圍為過去 60 秒。如果使用量(包括當前請求)在吞吐量限制內,則請求獲得批准。如果使用量超過限制,則請求被拒絕。

請求類型遊戲伺服器 API開放雲 API限制
讀取GetAsync()
GetVersionAsync()
GetVersionAtTimeAsync()
ListVersionsAsync()
UpdateAsync()
獲取數據存儲條目每分鐘 25 MB
寫入SetAsync()
IncrementAsync()
UpdateAsync()
RemoveAsync()
創建、更新、增量、刪除數據存儲條目每分鐘 4 MB

除了上述吞吐量限制外,Roblox 根據內部架構將數據組織到分區中。因此,當後端伺服器收到對同一數據存儲的高請求量時,可能會導致進一步的限制。無論原因如何,限制表現為 DatastoreThrottledKeyThrottled 錯誤,具體取決於是否超過了單個數據存儲或鍵的吞吐量限制。這些錯誤消息適用於有序和標準數據存儲。

存儲限制

為了保持存儲穩定和可擴展,數據存儲對您的存儲使用量使用遊戲級別的限制。

此限制由每個遊戲的基本分配加上基於終身用戶數的額外分配組成。終身用戶是指至少加入過您的遊戲一次的任何用戶。

存儲限制的計算公式為 Total latest version storage limit = 500 MB + 1 MB × lifetime user count

存儲使用量是使用每個鍵的最新版本的 壓縮大小 來衡量的。數據存儲在存儲之前會自動壓縮您的數據,因此請避免自己進行預壓縮。預壓縮會增加不必要的 CPU 開銷,並可能降低數據存儲內置壓縮的有效性。通過存儲未壓縮的數據,您自動受益於 Roblox 的壓縮算法和未來基於架構的優化的改進。

只有每個鍵的最新版本計入您的存儲使用量。已刪除的鍵和被取代的版本在其保留期間內仍可通過版本 API 訪問,但不計入您的存儲使用量。然而,通過開放雲 DeleteDataStore 方法刪除的數據存儲在其 30 天刪除處理期間內仍計入存儲使用量,直到它們被永久刪除。

©2026 Roblox Corporation、Roblox、Roblox 標誌及 Powering Imagination 是我們在美國及其他國家地區的部分註冊與未註冊商標。