データストアのエラーコードと制限

このページでは、データストアがリクエスト、データ、スループット、ストレージに対して強制する制限をリストし、続いて失敗したリクエストが返すエラーコードを示します。

制限

データモデルには制限があります。体験がこれらの制限を超えると、サービスは自動的に体験のデータストアの使用を制限し、将来のリクエストを次のいずれかのキューに配置します：

• セット
• 順序付きセット
• 取得
• 順序付き取得

キュー内のリクエストは、受信した順に処理されます。呼び出された関数は、そのリクエストがまだキューにある限り、継続して待機します。データストアキー自体が制限されている場合、リクエストはキューに配置されますが、一時的にスキップされます。

各キューには30リクエストの制限があります。キューの制限に達すると、リクエストは301-306の範囲のエラーコードで失敗し、リクエストが完全にドロップされたことを示します。

データ制限

データストアは、エントリごとに使用できるデータの量を制限します。

データストア名、キー名、およびスコープは、すべて特定の文字数制限内でなければなりません。string.len()を使用してその長さを確認してください。

データ（キー値）も、初期のタイプに関係なく文字列として保存されます。データのサイズは、LuauデータをシリアライズされたJSONテーブルに変換するJSONEncode()関数を使用して確認できます。

メタデータ制限

ユーザー定義メタデータの文字数制限。

スループット制限

キーごとのスループット制限は、Robloxサーバーでのパフォーマンスが最適であることを保証します。各制限は、体験内のすべてのサーバーにわたって各キーに適用され、時間とともにリフレッシュされます。

Robloxは、過去60秒間のキーに関連付けられたクォータの使用状況を調査します。使用状況がスループット制限内であれば、リクエストは承認されます。使用状況が制限を超えると、リクエストは拒否されます。

上記のスループット制限に加えて、Robloxは内部スキーマに基づいてデータをパーティションに整理します。その結果、バックエンドサーバーが同じデータストアへの高ボリュームのリクエストを受け取ると、さらなる制限がかかる可能性があります。原因に関係なく、制限はDatastoreThrottledまたはKeyThrottledエラーとして現れます。これは、スループット制限が単一のデータストアまたはキーに対して超過したかどうかによります。これらのエラーメッセージは、順序付きデータストアと標準データストアの両方に適用されます。

ストレージ制限

ストレージを安定させ、スケーラブルに保つために、データストアはゲームレベルのストレージ使用制限を使用します。

この制限は、各ゲームの基本割り当てに加え、ライフタイムユーザーの数に基づく追加の割り当てで構成されます。ライフタイムユーザーとは、あなたのゲームに少なくとも一度参加したユーザーのことです。

ストレージ制限は、次の式を使用して計算されます Total latest version storage limit = 500 MB + 1 MB × lifetime user count。

ストレージ使用量は、各キーの最新バージョンの圧縮サイズを使用して測定されます。データストアは自動的にデータをストレージ前に圧縮するため、事前に圧縮することは避けてください。事前圧縮は不必要なCPUオーバーヘッドを追加し、データストアの組み込み圧縮の効果を減少させる可能性があります。圧縮されていないデータを保存することで、Robloxの圧縮アルゴリズムの改善や将来のスキーマベースの最適化の恩恵を自動的に受けることができます。

各キーの最新バージョンのみがストレージ使用量にカウントされます。削除されたキーや置き換えられたバージョンは、保持期間中にバージョンAPIを通じてアクセス可能ですが、ストレージ使用量にはカウントされません。ただし、オープンクラウドのDeleteDataStoreメソッドを通じて削除されたデータストアは、永久に削除されるまでの30日間の削除処理期間中はストレージ使用量にカウントされ続けます。

アクセス制限

データストアは、体験およびサーバーレベルの制限の対象です。体験レベルの制限は、体験全体の同時ユーザー数に応じてスケールし、サーバーレベルの制限は設定可能で、クリエイターがツールとして使用することを目的としています。

体験制限

各体験には、データストアのタイプ、リクエストタイプ、および同時ユーザー数に基づいて、特定の数のデータストアリクエストが許可されています。各データストアタイプおよびリクエストタイプについて、制限はすべてのリストされた関数で共有されます。

• UpdateAsync()は、読み取りおよび書き込みリクエストの予算の両方から消費します。単一の呼び出しは両方の制限を減少させます。
• ゲームサーバーとオープンクラウドは予算を共有します。オープンクラウドのトラフィックは、体験内の使用によって制限される可能性があります（その逆も同様です）。詳細なガイダンスについては、制限を制御するを参照してください。

標準データストア

順序付きデータストア

制限を制御する

オープンクラウドとゲームサーバーのリクエストは共有されるため、それぞれが予算からどれだけ消費できるかを独立して制御することが重要です。

ゲームサーバー

個々のサーバーには、上記のように組み込みの制限があります。SetRateLimitForRequestType()とGetRequestBudgetForRequestType()の組み合わせを使用して、個々のサーバーの総予算への貢献を細かく制御します。

オープンクラウド

オープンクラウドのリクエストには、外部のレート制限ソリューションが必要です。以下のアプローチのいずれかを推奨します：

• （シンプル）各リクエストの後に短いタイムアウトを追加します。特に、同じAPIを連続ループで呼び出す場合は、タイムアウトを60 / (desired budget consumption per minute)秒に設定します。このアプローチでは、リクエストをバーストで送信することはできません。
• （堅牢）漏れバケツ戦略を使用してローカルレートリミッターを実装します。

以下のNode.jsコードサンプルには、参照実装が含まれています。

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('API_KEY環境変数が設定されていません。');
}

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(`\nエントリを処理中: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`ステータス: ${updateResponse.status}`);
            console.log(`レスポンス: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('実行中にエラーが発生しました:', error);
    }
})();

サーバー制限

各サーバーには、そのサーバー内のプレイヤー数に基づいて、各リクエストタイプの設定可能なレート制限があります。サーバーは、最初に作成されたときに追加のリクエスト予算の一時的なバーストを受け取ります。GetRequestBudgetForRequestType()を使用して、現在のサーバーがいつでも行えるデータストアリクエストの数を確認します。

これらの制限は、クリエイターによって設定可能です。 SetRateLimitForRequestType() APIを使用することで、クリエイターは各リクエストタイプのデータストアのレート制限を設定できます。

以下のデフォルトレート制限は、APIが呼び出されない場合に適用されます：

標準データストア

順序付きデータストア

エラーコードリファレンス

データストアへのリクエストは、接続が不良であるか、他の問題により失敗する可能性があります。エラーを処理し、エラーコードを持つメッセージを返すには、データストア関数をpcall()でラップします。

UpdateAsync()のような失敗した書き込み呼び出しは、ゲームサーバーが成功した応答を受け取らなかったことを意味します。バックエンドの書き込みが発生しなかったことを常に保証するわけではありません。いくつかの失敗シナリオでは、最終的な書き込み状態は、キャッシュなしでフォローアップの読み取りで確認されるまで呼び出し元には不明な場合があります。

サーバーエラーコード