Códigos de error y límites de la tienda de datos

Las solicitudes que realices a las tiendas 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 de la tienda 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 de backend no haya ocurrido. En algunos escenarios de fallo, el estado final de la escritura puede ser desconocido para el llamador hasta que se verifique con una lectura posterior 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 de la tienda de datos de la experiencia y coloca futuras solicitudes en una de las siguientes colas:

• Establecer
• Conjunto 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 siga en la cola. Si la clave de la tienda de datos en sí está limitada, la solicitud se coloca en una cola, pero se salta 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 completamente descartadas.

Límites de acceso

Las tiendas de datos están sujetas tanto a límites de experiencia como a límites del servidor. Los límites a nivel de experiencia se escalan con el total de usuarios concurrentes en la experiencia, mientras que los límites a 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 tienda de datos basado en el tipo de tienda de datos, el tipo de solicitud y el número de usuarios concurrentes. Para cada tipo de tienda de datos y tipo de solicitud, el límite es compartido entre todas las funciones listadas.

• UpdateAsync() consume tanto del presupuesto de solicitudes de lectura como de escritura. Una sola llamada disminuirá ambos límites.
• El servidor de 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 los límites de tasa para obtener más orientación.

Tiendas de datos estándar

Tiendas de datos ordenadas

Controlar límites de tasa

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

Servidor de juego

Los servidores individuales tienen límites incorporados, como se describió anteriormente. Utiliza 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 de limitación de tasa externa. Te recomendamos uno de los siguientes enfoques:

• (Simple) Agregar un corto 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 que las solicitudes se envíen en ráfagas.
• (Robusto) Implementar un limitador de tasa local utilizando la estrategia de cubo con fuga.

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 para cada operación: 60 / (solicitudes por minuto) 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 regresar.
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 impulso de presupuesto de solicitud adicional de una sola vez cuando se crean por primera vez. Usa GetRequestBudgetForRequestType() para confirmar el número de solicitudes de tienda de datos que el servidor actual puede hacer en cualquier momento dado.

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

Los siguientes límites de tasa por defecto se aplican si la API no se llama:

Tiendas de datos estándar

Tiendas de datos ordenadas

Límites de datos

Las tiendas de datos limitan cuánto se puede usar por entrada.

El nombre de la tienda de datos, el nombre de la clave y el alcance deben estar todos por debajo de cierta longitud de carácter. Utiliza string.len() para comprobar su longitud.

Los datos (valor de clave) también se almacenan como una cadena, independientemente de su tipo inicial. Puedes comprobar 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 en una experiencia y se actualiza con el tiempo.

Roblox examina el uso de la cuota asociada a 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 supera el límite, la solicitud es denegada.

Además de los límites de rendimiento mencionados, Roblox organiza datos en particiones basadas en un esquema interno. Como resultado, cuando el servidor backend recibe un alto volumen de solicitudes a la misma tienda de datos, puede resultar en una mayor limitación. 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 una sola tienda de datos o una clave. Estos mensajes de error se aplican tanto a tiendas de datos ordenadas como estándar.

Límites de almacenamiento

Para mantener el almacenamiento estable y escalable, las tiendas de datos utilizan un límite a nivel de juego sobre 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 × recuento de usuarios de por vida.

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

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