21 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Data store error codes and limits

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 LuaGlobals.pcall().

A failed write call, such as UpdateAsync(), means the game server did not receive a successful response. It does not always guarantee that the backend write did not occur. In some failure scenarios, the final write state may be unknown to the caller until it is verified with a follow-up read without cache.

Error code reference

Server error codes

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.

Access limits

Data stores are subject to both experience and server-level limits. Experience-level limits scale with total concurrent users across the experience, while server-level limits are configurable and meant to be used as a tool by the creator.

Experience Limits

Each experience is allowed a certain number of data store requests based on the data store type, request type, and number of concurrent users. For each data store type and request type, the limit is shared among all listed functions.

• UpdateAsync() consumes from both the read and write request budgets. A single call will decrement both limits.
• Game server and Open Cloud share a budget; Open Cloud traffic can be throttled by in-experience usage (and vice versa). See Control rate limits for further guidance.

Standard data stores

Ordered data stores

Control rate limits

Because Open Cloud and game server requests are shared, it is important to independently control how much each can consume from the budget.

Game server

Individual servers have built-in limits, as described above. Use a combination of SetRateLimitForRequestType() and GetRequestBudgetForRequestType() to maintain fine-grained control over individual servers' contribution to the total budget.

Open Cloud

Open Cloud requests require an external rate limiting solution. We recommend one of the following approaches:

• (Simple) Add a short timeout after each request, especially if calling the same API in a continuous loop. Set this timeout equal to 60 / (desired budget consumption per minute) seconds, as an upper bound. Note that this approach does not allow requests to be sent in bursts.
• (Robust) Implement a local rate limiter using the leaky bucket strategy.

The following Node.js code samples include reference implementations.

Timeout rate limiting

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/';

// --- Per-operation rate limiting config (requests per minute) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Upper-bound spacing per operation: 60 / (requests per min) seconds.
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));

// Performs the request, then waits this operation's own interval before returning.
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) // The body must be a string
    }, 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);
    }
})();

Leaky bucket rate limiting

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 sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// --- Leaky bucket rate limiter ---
// `capacity`      : max burst size (how full the bucket can get).
// `leakRatePerSec`: steady drain rate == sustained requests/sec allowed.
class LeakyBucket {
    constructor({ capacity, leakRatePerSec }) {
        this.capacity = capacity;
        this.leakRatePerSec = leakRatePerSec;
        this.level = 0;
        this.lastLeak = Date.now();
        // Serialize acquisitions so concurrent callers queue fairly.
        this.tail = Promise.resolve();
    }

    _leak() {
        const now = Date.now();
        const elapsedSec = (now - this.lastLeak) / 1000;
        this.level = Math.max(0, this.level - elapsedSec * this.leakRatePerSec);
        this.lastLeak = now;
    }

    // Resolves once there is room in the bucket for one more request.
    acquire() {
        const attempt = this.tail.then(async () => {
            this._leak();
            while (this.level + 1 > this.capacity) {
                const overflow = this.level + 1 - this.capacity;
                const waitMs = (overflow / this.leakRatePerSec) * 1000;
                await sleep(waitMs);
                this._leak();
            }
            this.level += 1;
        });
        // Keep the chain alive even if a caller rejects.
        this.tail = attempt.catch(() => {});
        return attempt;
    }
}

// --- One bucket per operation ---
// Example: list bursts of 5 @ 1/sec, get bursts of 10 @ 2/sec, update bursts of 5 @ 1/sec.
const listBucket = new LeakyBucket({ capacity: 5, leakRatePerSec: 1 });
const getBucket = new LeakyBucket({ capacity: 10, leakRatePerSec: 2 });
const updateBucket = new LeakyBucket({ capacity: 5, leakRatePerSec: 1 });

// Waits for the given bucket's capacity before each request.
async function rateLimitedFetch(bucket, url, options) {
    await bucket.acquire();
    return fetch(url, options);
}

async function listEntries(universe, dataStore) {
    const listPath = `universes/${universe}/data-stores/${dataStore}/entries`;
    const url = baseUrl + listPath;
    const response = await rateLimitedFetch(listBucket, url, {
        headers: { [apiHeaderKey]: apiKey }
    });
    return response.json();
}

async function getEntry(path) {
    const url = baseUrl + path;
    const response = await rateLimitedFetch(getBucket, url, {
        headers: { [apiHeaderKey]: apiKey }
    });
    return response.json();
}

async function updateEntry(path, payload) {
    const url = baseUrl + path;
    const response = await rateLimitedFetch(updateBucket, url, {
        method: 'PATCH',
        headers: {
            [apiHeaderKey]: apiKey,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload) // The body must be a string
    });
    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);
    }
})();

Server limits

Each server has a configurable rate limit for each request type, based on the number of players in that server. Servers receive a one-time startup burst of additional request budget when they are first created. Use GetRequestBudgetForRequestType() to confirm the number of data store requests that the current server can make at any given time.

These limits are configurable by the creator using the SetRateLimitForRequestType() API. Using this API, a creator can configure their own data stores rate limits for each request type.

The following default rate limits apply if the API is not called:

Standard data stores

Ordered data stores

Note

Data store requests made in Studio Run mode are subject to a separate set of static limits, which may be lower than the limits configured with [`SetRateLimitForRequestType()`](/docs/datastoreservice#datastoreservice-setratelimitforrequesttype). When testing rate limits, we recommend using Studio Team Create instead.

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 Luau data into a serialized JSON table.

Metadata limits

Limits to the number of characters in user-defined metadata.

Note

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.

In addition to the above throughput limits, Roblox organizes data into partitions based on an internal schema. As a result, when the backend server receives a high volume of requests to the same data store, it can result in further throttling. Regardless of the cause, throttling manifests as either DatastoreThrottled or KeyThrottled errors, depending on whether the throughput limit was exceeded for a single data store or a key. These error messages apply to both ordered and standard data stores.

Note

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).

Storage limits

To keep storage stable and scalable, data stores use a game-level limit on your storage usage.

This limit consists of a base allocation for each game plus an additional allocation based on the number of lifetime users. A lifetime user is any user who has joined your game at least once.

The storage limit is calculated using the following formula Total latest version storage limit = 500 MB + 1 MB × lifetime user count.

Storage usage is measured using the compressed size of the latest version of each key. Data stores automatically compress your data before storage, so avoid pre-compressing it yourself. Pre-compression adds unnecessary CPU overhead and may reduce the effectiveness of data stores' built-in compression. By storing uncompressed data, you automatically benefit from improvements to Roblox's compression algorithms and future schema-based optimizations.

Only the latest version of each key counts toward your storage usage. Deleted keys and superseded versions, while still accessible through version APIs during their retention period, do not count toward your storage usage. However, data stores deleted through the Open Cloud DeleteDataStore method continue to count toward storage usage during their 30-day deletion processing period, until they are permanently removed.