Códigos de error y límites de almacenamiento de datos

Las solicitudes que realizas a los almacenes de datos pueden fallar debido a una mala conectividad u otros problemas. Para manejar errores y devolver mensajes con un código de error, envuelve las funciones del almacén de datos en pcall().

Una llamada de escritura fallida, como UpdateAsync(), significa que el servidor del juego no recibió una respuesta exitosa. No siempre garantiza que la escritura en el backend no haya ocurrido. En algunos escenarios de falla, el estado final de la escritura puede ser desconocido para el llamador hasta que se verifique con una lectura de seguimiento sin caché.

Referencia de códigos de error

Códigos de error del servidor

Límites

Los modelos de datos tienen límites. Si una experiencia excede estos límites, el servicio limita automáticamente el uso del almacén de datos de la experiencia y provoca que las solicitudes futuras se coloquen en una de las siguientes colas:

• Establecer
• Establecer ordenado
• Obtener
• Obtener ordenado

Las solicitudes en una cola se manejan en el orden en que se reciben. La función llamada continúa cediendo mientras su solicitud aún esté en cola. Si la clave del almacén de datos en sí está limitada, la solicitud se coloca en una cola pero se omite temporalmente.

Cada cola tiene un límite de 30 solicitudes. Cuando se alcanza el límite de una cola, las solicitudes fallan con un código de error en el rango 301-306, indicando que las solicitudes han sido descartadas por completo.

Límites de acceso

Los almacenes de datos están sujetos a límites de experiencia y de nivel de servidor. Los límites de nivel de experiencia escalan con el número total de usuarios concurrentes en la experiencia, mientras que los límites de nivel de servidor son configurables y están destinados a ser utilizados como una herramienta por el creador.

Límites de experiencia

Cada experiencia tiene permitido un cierto número de solicitudes de almacén de datos según el tipo de almacén de datos, el tipo de solicitud y el número de usuarios concurrentes. Para cada tipo de almacén de datos y tipo de solicitud, el límite se comparte entre todas las funciones enumeradas.

• UpdateAsync() consume tanto del presupuesto de solicitudes de lectura como de escritura. Una sola llamada disminuirá ambos límites.
• El servidor del juego y Open Cloud comparten un presupuesto; el tráfico de Open Cloud puede ser limitado por el uso en la experiencia (y viceversa). Consulta Controlar límites de tasa para obtener más orientación.

Almacenes de datos estándar

Almacenes de datos ordenados

Controlar límites de tasa

Debido a que las solicitudes de Open Cloud y del servidor del juego son compartidas, es importante controlar de manera independiente cuánto puede consumir cada una del presupuesto.

Servidor del juego

Los servidores individuales tienen límites incorporados, como se describió anteriormente. Usa una combinación de SetRateLimitForRequestType() y GetRequestBudgetForRequestType() para mantener un control detallado sobre la contribución de los servidores individuales al presupuesto total.

Open Cloud

Las solicitudes de Open Cloud requieren una solución externa de limitación de tasa. Recomendamos uno de los siguientes enfoques:

• (Simple) Agrega un breve tiempo de espera después de cada solicitud, especialmente si llamas a la misma API en un bucle continuo. Establece este tiempo de espera igual a 60 / (consumo de presupuesto deseado por minuto) segundos, como un límite superior. Ten en cuenta que este enfoque no permite enviar solicitudes en ráfagas.
• (Robusto) Implementa un limitador de tasa local utilizando la estrategia de cubo con fugas.

Los siguientes ejemplos de código en Node.js incluyen implementaciones de referencia.

const apiKey = process.env.API_KEY;
if (!apiKey) {
    throw new Error('La variable de entorno API_KEY no está configurada.');
}

const apiHeaderKey = 'x-api-key';

const universeId = '';
const dataStoreId = 'Inventario';

const baseUrl = 'https://apis.roblox.com/cloud/v2/';

// --- Configuración de limitación de tasa por operación (solicitudes por minuto) ---
const LIST_RATE_PER_MIN = 60;
const GET_RATE_PER_MIN = 120;
const UPDATE_RATE_PER_MIN = 60;

// Espaciado superior por operación: 60 / (solicitudes por min) segundos.
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));

// Realiza la solicitud, luego espera el intervalo de esta operación antes de devolver.
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) // El cuerpo debe ser una cadena
    }, 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(`\nProcesando entrada: ${path}`);

            const currentData = await getEntry(path);

            currentData.value.currency += 10;

            const payload = { value: currentData.value };

            const updateResponse = await updateEntry(path, payload);

            console.log(`Estado: ${updateResponse.status}`);
            console.log(`Respuesta: ${await updateResponse.text()}`);
        }
    } catch (error) {
        console.error('Ocurrió un error durante la ejecución:', error);
    }
})();

Límites del servidor

Cada servidor tiene un límite de tasa configurable para cada tipo de solicitud, basado en el número de jugadores en ese servidor. Los servidores reciben un aumento de presupuesto de solicitudes adicional único cuando se crean por primera vez. Usa GetRequestBudgetForRequestType() para confirmar el número de solicitudes de almacén de datos que el servidor actual puede realizar en cualquier momento.

Estos límites son configurables por el creador utilizando la API SetRateLimitForRequestType(). Usando esta API, un creador puede configurar sus propios límites de tasa de almacenes de datos para cada tipo de solicitud.

Los siguientes límites de tasa predeterminados se aplican si no se llama a la API:

Almacenes de datos estándar

Almacenes de datos ordenados

Límites de datos

Los almacenes de datos limitan cuánto se puede usar por entrada.

El nombre del almacén de datos, el nombre de la clave y el alcance deben estar todos bajo una cierta longitud de caracteres. Usa string.len() para verificar su longitud.

Los datos (valor de clave) también se almacenan como una cadena, independientemente de su tipo inicial. Puedes verificar el tamaño de los datos con la función JSONEncode(), que convierte datos de Luau en una tabla JSON serializada.

Límites de metadatos

Límites al número de caracteres en los metadatos definidos por el usuario.

Límites de rendimiento

Los límites de rendimiento por clave aseguran que el rendimiento sea óptimo en los servidores de Roblox. Cada límite se aplica a cada clave individual en todos los servidores de una experiencia y se actualiza con el tiempo.

Roblox examina el uso de la cuota asociada con la clave durante los últimos 60 segundos. Si el uso, incluida la solicitud actual, está dentro del límite de rendimiento, la solicitud es aprobada. Si el uso excede el límite, la solicitud es denegada.

Además de los límites de rendimiento anteriores, Roblox organiza los datos en particiones basadas en un esquema interno. Como resultado, cuando el servidor backend recibe un alto volumen de solicitudes al mismo almacén de datos, puede resultar en una limitación adicional. Independientemente de la causa, la limitación se manifiesta como errores DatastoreThrottled o KeyThrottled, dependiendo de si se excedió el límite de rendimiento para un solo almacén de datos o una clave. Estos mensajes de error se aplican tanto a almacenes de datos ordenados como estándar.

Límites de almacenamiento

Para mantener el almacenamiento estable y escalable, los almacenes de datos utilizan un límite de nivel de juego en tu uso de almacenamiento.

Este límite consiste en una asignación base para cada juego más una asignación adicional basada en el número de usuarios de por vida. Un usuario de por vida es cualquier usuario que se haya unido a tu juego al menos una vez.

El límite de almacenamiento se calcula utilizando la siguiente fórmula Límite total de almacenamiento de la última versión = 500 MB + 1 MB × número de usuarios de por vida.

El uso de almacenamiento se mide utilizando el tamaño comprimido de la última versión de cada clave. Los almacenes de datos comprimen automáticamente tus datos antes del almacenamiento, así que evita comprimirlos tú mismo. La precompresión agrega una sobrecarga innecesaria de CPU y puede reducir la efectividad de la compresión incorporada de los almacenes de datos. Al almacenar datos sin comprimir, te beneficias automáticamente de las mejoras en los algoritmos de compresión de Roblox y de futuras optimizaciones basadas en esquemas.

Solo la última versión de cada clave cuenta para tu uso de almacenamiento. Las claves eliminadas y las versiones superadas, aunque aún son accesibles a través de las API de versiones durante su período de retención, no cuentan para tu uso de almacenamiento. Sin embargo, los almacenes de datos eliminados a través del método Open Cloud DeleteDataStore continúan contando para el uso de almacenamiento durante su período de procesamiento de eliminación de 30 días, hasta que sean eliminados permanentemente.