Requests you make to data stores can fail due to poor connectivity or other issues. To handle errors and return messages with an error code, wrap data store functions in pcall().
Error Code Reference
| Error Code | Error Name | Error Message | Notes | |
|---|---|---|---|---|
| 101 | KeyNameEmpty | Key name can't be empty. | Check if the key input into the data store function is an empty string. | |
| 102 | KeyNameLimit | Key name exceeds the 50 character limit. | Check if the key input into the data store function exceeds a length of 50. | |
| 103 | ValueNotAllowed | Can't allow X in DataStore. | A bad update function returned a value of type X. | |
| 104 | CantStoreValue | Can't store X in DataStore. | The update function returned a value of type X that didn't serialize. | |
| 105 | ValueTooLarge | Serialized value exceeds X limit. | If you're setting a value with SetAsync() or UpdateAsync(), the serialized length of the value can't exceed the size X. To check the serialized length of the data, use JSONEncode(). | |
| 106 | MaxValueInvalid | MaxValue must be an integer. | If you're passing a maximum value to GetSortedAsync() for an OrderedDataStore, it must be an integer. | |
| 106 | MinValueInvalid | MinValue must be an integer. | If you're passing a minimum value to GetSortedAsync() for an OrderedDataStore, it must be an integer. | |
| 106 | PageSizeGreater | PageSize must be within a predefined range. | The minimum page size for an OrderedDataStore is 1. | |
| 106 | PageSizeLesser | PageSize must be within a predefined range. | The maximum page size for an OrderedDataStore is 100. | |
| 107 | MinMaxOrderInvalid | MaxValue must be greater than or equal to MinValue. | The maximum value must be greater than or equal to the minimum value for GetSortedAsync(). | |
| 301 | GetAsyncThrottle | GetAsync request dropped. Request was throttled but queue was full. | GetAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 302 | SetAsyncThrottle | SetAsync request dropped. Request was throttled but queue was full. | SetAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 303 | IncreAsyncThrottle | IncrementAsync request dropped. Request was throttled but queue was full. | IncrementAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 304 | UpdateAsyncThrottle | UpdateAsync request dropped. Request was throttled but queue was full. | UpdateAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 304 | TransformThrottle | UpdateAsync request dropped. Request was throttled but queue was full. | UpdateAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 305 | GetSortedThrottle | GetSorted request dropped. Request was throttled but queue was full. | GetSortedAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 306 | RemoveAsyncThrottle | RemoveAsync request dropped. Request was throttled but queue was full. | RemoveAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | |
| 401 | DataModelNoAccess | Request failed. DataModel is inaccessible while the experience is shutting down. | DataModel is uninitialized because the experience is shutting down. | |
| 402 | LuaWebSrvsNoAccess | Request failed. LuaWebService is inaccessible while the experience is shutting down. | LuaWebService is uninitialized because the experience is shutting down. | |
| 403 | StudioAccessToApisNotAllowed | Can't write to DataStore from Studio because API access is not enabled. | API access must be active in order to use Data Stores in Studio. | |
| 404 | InternalError | OrderedDataStore doesn't exist. | The OrderedDataStore associated with this request wasn't found. This might be a sign of data corruption. Try again later. | |
| 501 | InternalError | Can't parse response because data might be corrupted. | The server was unable to parse the response to your request. This might be a sign of data corruption. Try again later. | |
| 502 | RequestRejected | API Services rejected the request with error X. | Error X occurred when processing on Roblox servers. Try again later. | |
| 503 | InternalError | Data store request was successful but key wasn't found. | The key requested wasn't found in the Data Store. This might be a sign of data corruption. Try again later. | |
| 504 | InternalError | Data Store request was successful but the response wasn't formatted correctly. | The server was unable to parse the response to your request. This might be a sign of data corruption. Try again later. | |
| 505 | InternalError | OrderedDataStore request was successful but the response wasn't formatted correctly. | The server was unable to parse the response to your OrderedDataStore request. This might be a sign of data corruption. Try again later. | |
| 509 | OperationNotAllowed | Data Store operations are blocked while running on a Personal RCC to prevent possible data corruption. | Data Store writes are blocked on private RCC channels. | |
| 511 | AttributeSizeTooLarge | Metadata attribute size exceeds X limit. | The serialized metadata size exceeds the limit of X. The value X is dynamic. If the size changes, the value also changes. | |
| 512 | UserIdLimitExceeded | UserID size exceeds X limit. | The length of the user IDs array provided by the user exceeds the limit of X. | |
| 513 | AttributeFormatError | Attribute userId format is invalid. | The user ID provided isn't a number. | |
| 513 | AttributeFormatError | Attribute metadata format is invalid. | The metadata isn't a table. | |
| GetVersionAsyncThrottle | GetVersionAsync request dropped. Request was throttled. | GetVersionAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | ||
| GetVersionAtTimeAsyncThrottle | GetVersionAtTimeAsync request dropped. Request was throttled. | GetVersionAtTimeAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | ||
| ListDataStoresAsyncThrottle | ListDataStoresAsync request dropped. Request was throttled. | ListDataStoresAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | ||
| ListKeysAsyncThrottle | ListKeysAsync request dropped. Request was throttled. | ListKeysAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | ||
| ListVersionsAsyncThrottle | ListVersionsAsync request dropped. Request was throttled. | ListVersionsAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | ||
| RemoveVersionAsyncThrottle | RemoveVersionAsync request dropped. Request was throttled. | RemoveVersionAsync() request has exceeded the maximum queue size and Roblox is unable to process the requests at the current throughput. | ||
| InvalidTimestamp | Timestamp must be positive and not more than ten minutes in the future. | The timestamp provided to GetVersionAtTimeAsync() was not valid. |
Server Error Codes
| Error Name | Error Message | Notes |
|---|---|---|
| DatastoreThrottled | The request rate exceeds the allowed maximum for the datastore. | Too many requests were sent to a single Data Store. |
| InternalServerError | An internal server error occurred. | Occasional error on Roblox servers. Try again, ideally with exponential backoff. |
| InvalidPlace | The provided place is invalid. | No matching Universe ID for the place. Try again later. |
| InvalidTarget | The provided target is invalid. | Ordered Data Store key name exceeds the 50 character limit. |
| InvalidUniverse | The provided universe is invalid. | No matching Place ID for the universe. Try again later. |
| InvalidUserIds | The provided user IDs have an invalid format. | Failed to parse user IDs. |
| KeyThrottled | The request rate exceeds the allowed maximum for the key. | The request rate exceeds the maximum allowed request rate for a single key. |
| KeyNotFound | The requested key doesn't exist. | The key doesn't exist. |
| N/A | No pages to advance to. | This error occurs when you call Pages:AdvanceToNextPageAsync() on the last page. |
Limits
Data models have limits. If an experience exceeds these limits, the service automatically throttles the experience's data store usage and causes future requests to be placed in one of the following queues:
- Set
- Ordered set
- Get
- Ordered get
Requests in a queue are handled in the order they are received. The called function continues to yield as long as its request is still queued. If the data store key itself is throttled, the request is placed in a queue but is temporarily skipped.
Each queue has a limit of 30 requests. When the limit of a queue is reached, requests fail with an error code in the 301-306 range, indicating that the requests have been dropped entirely.
Server Limits
Each server is allowed a certain number of data store requests based on the request type and number of users. Use GetRequestBudgetForRequestType() to confirm the number of data store requests that the current place can make.
| Request Type | Functions | Requests per Minute |
|---|---|---|
| Get | GetAsync() | 60 + numPlayers × 10 |
| Set (limit is shared among all listed functions) | SetAsync() IncrementAsync() UpdateAsync() RemoveAsync() | 60 + numPlayers × 10 |
| Get Sorted | GetSortedAsync() | 5 + numPlayers × 2 |
| Get Version | GetVersionAsync() GetVersionAtTimeAsync() | 5 + numPlayers × 2 |
| List | ListDataStoresAsync() ListKeysAsync() ListVersionAsync() | 5 + numPlayers × 2 |
| Remove | RemoveVersionAsync() | 5 + numPlayers × 2 |
Data Limits
Data stores limit how much data can be used per entry.
The data store name, key name, and scope must all be under a certain character length. Use string.len() to check their length.
The data (key value) is also stored as a string, regardless of its initial type. You can check the size of the data with the JSONEncode() function, which converts Lua data into a serialized JSON table.
| Component | Maximum Number of Characters |
|---|---|
| Data Store Name | 50 |
| Key Name | 50 |
| Scope | 50 |
| Data (Key Value) | 4,194,304 per key |
Metadata Limits
Limits to the number of characters in user-defined metadata.
| Component | Maximum Number of Characters |
|---|---|
| Key Name | 50 |
| Value | 250 |
| Key-value Pairs | 300 |
There's no limit to the total number of key-value pairs, but the total size can't exceed 300 characters.
Throughput Limits
Per-key throughput limits ensure that performance is optimal on Roblox servers. Each limit applies to every single key across all servers in an experience and refreshes over time.
Roblox examines the usage of quota associated with the key over the last 60 seconds. If the usage, including the current request, is within the throughput limit, the request is approved. If the usage exceeds the limit, the request is denied.
| Request Type | Limit |
|---|---|
| Read | 25 MB per minute |
| Write | 4 MB per minute |
For every request, Roblox rounds throughput up to the next kilobyte. For example, if you write 800 bytes and 1.2 KB in two requests, Roblox counts that as 3 KB total throughput (1 KB and 2 KB, respectively).