Límite de velocidad y CORS

Límite de velocidad

Para mantener el servicio estable, RyzeAPI aplica un límite de solicitudes por minuto. El límite se cuenta por token: todos los que usen el mismo token comparten el mismo bucket.

Tipo de solicitud	Límite predeterminado
La mayoría de los endpoints	100 solicitudes por minuto
Creación de instancia (`POST /api/instance/new`)	20 solicitudes por minuto

Si necesitas un límite más alto para tu cuenta, contacta con soporte.

Headers de límite de velocidad

Todas las respuestas (incluyendo las exitosas) incluyen tres headers que permiten a tu cliente adaptarse:

Header	Significado
`X-RateLimit-Limit`	Límite máximo en el período actual (por ejemplo, `100`)
`X-RateLimit-Remaining`	Cuántas solicitudes están aún disponibles
`X-RateLimit-Reset`	Timestamp Unix (segundos) de cuándo se reinicia el contador

Usa X-RateLimit-Remaining para implementar backoff exponencial antes de alcanzar el límite. Por ejemplo: cuando baje de 10, espera un poco antes de la siguiente llamada.

Qué ocurre cuando lo excedes

La API responde con HTTP 429 Too Many Requests:

{
  "success": false,
  "error": {
    "message": "Rate limit exceeded. Try again later."
  }
}

Los headers X-RateLimit-* continúan enviándose, usa X-RateLimit-Reset para saber cuándo puedes intentar de nuevo.

Ejemplo de manejo

async function callAPI(path, options = {}) {
  const res = await fetch(`https://ryzeapi.cloud${path}`, options);

  // If you exceeded the limit, wait until the reset
  if (res.status === 429) {
    const resetAt = parseInt(res.headers.get("X-RateLimit-Reset"), 10) * 1000;
    const waitMs = Math.max(1000, resetAt - Date.now());
    await new Promise(r => setTimeout(r, waitMs));
    return callAPI(path, options); // retry
  }

  // Preventive backoff: if close to the limit, slow down
  const remaining = parseInt(res.headers.get("X-RateLimit-Remaining"), 10);
  if (remaining < 10) {
    await new Promise(r => setTimeout(r, 500));
  }

  return res.json();
}

CORS

Si estás llamando a la API desde un navegador (JavaScript ejecutándose en una página web), debes prestar atención al CORS.

Orígenes permitidos

RyzeAPI acepta solicitudes solo desde los orígenes autorizados para tu cuenta. Los orígenes no autorizados reciben el clásico error de CORS en la consola del navegador:

Access to fetch at 'https://ryzeapi.cloud/...' from origin 'https://mysite.com'
has been blocked by CORS policy.

Si tu aplicación frontend necesita llamar a RyzeAPI, pide a soporte que añada tu origen (https://mysite.com) a la allowlist de tu cuenta.

Métodos y headers aceptados

La API responde al preflight (OPTIONS) con los siguientes headers:

Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization, token
Access-Control-Expose-Headers: Content-Length

Puedes enviar solicitudes con cualquier método HTTP usado por la API y con los headers Content-Type, Authorization o token.

Sin cookies

RyzeAPI no usa cookies para autenticación, el token va en el header token. Por lo tanto, no es necesario (ni está soportado) enviar credentials: "include" en las solicitudes fetch.

WebSocket en navegador

Como el JavaScript de navegador no permite personalizar headers en new WebSocket(...), la única forma de autenticar es vía query string:

const ws = new WebSocket(
  `wss://ryzeapi.cloud/ws/$Instance_Name?token=${instanceToken}`
);

El WebSocket también sigue la allowlist de orígenes de tu cuenta.

Checklist

Implementa backoff basado en X-RateLimit-Remaining para no ser bloqueado.

Maneja HTTP 429 reintentando después de X-RateLimit-Reset.

Si usas el navegador, pide a soporte que añada tu origen a la allowlist.

Para WebSocket en el navegador, pasa el token vía ?token= en la URL.

Primeros pasos

Fundamentos

MCP

Límite de velocidad y CORS