Fluyio Developers

Fluyio limita las peticiones por clave API para mantener un uso estable del servicio.

Dos ventanas

Cada petición debe caber en las dos ventanas independientes:

Ventana	Límite	Uso
Ráfaga	150 peticiones cada 10 segundos	Controla picos de tráfico.
Sostenida	600 peticiones cada 60 segundos	Limita el volumen continuo.

Agotar cualquiera de las ventanas produce un 429 aunque quede capacidad en la otra. La medición es por clave; separa credenciales por integración y coordina con soporte los volúmenes que necesites.

Cabeceras

Las cabeceras reflejan la ventana más restrictiva.

Cabecera	Ejemplo	Significado
`Ratelimit-Limit`	`150`	Máximo de peticiones de la ventana.
`Ratelimit-Remaining`	`87`	Peticiones restantes.
`Ratelimit-Reset`	`1715800230`	Instante Unix en segundos UTC en que se libera capacidad.
`Ratelimit-Policy`	`150;w=10, 600;w=60`	Política de ambas ventanas.

HTTP/1.1 200 OK
Content-Type: application/json
Fluyio-Request-Id: req_3f9a1c7e5b2d8f4a6c0e9b1d3f
Ratelimit-Limit: 150
Ratelimit-Remaining: 87
Ratelimit-Reset: 1715800230
Ratelimit-Policy: 150;w=10, 600;w=60

También se envían los alias X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset con los mismos valores.

Respuesta 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 4
Ratelimit-Limit: 150
Ratelimit-Remaining: 0
Ratelimit-Reset: 1715800234
Fluyio-Request-Id: req_3f9a1c7e5b2d8f4a6c0e9b1d3f

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Burst limit reached (150 req / 10s). Retry after 4 seconds.",
    "request_id": "req_3f9a1c7e5b2d8f4a6c0e9b1d3f"
  }
}

Respeta los segundos indicados por Retry-After. Repetir inmediatamente las peticiones aumenta los errores y retrasa el trabajo.

Reintentar un 429

async function fluyioFetch(url: string, init: RequestInit, attempt = 0): Promise<Response> {
  const res = await fetch(url, init);
  if (res.status !== 429 || attempt >= 5) return res;

  const retryAfter = Number(res.headers.get('retry-after') ?? '1');
  const jitter = Math.random() * 0.5; // up to 500 ms
  const wait = (retryAfter + jitter) * 1000 * 2 ** attempt;

  await new Promise((r) => setTimeout(r, wait));
  return fluyioFetch(url, init, attempt + 1);
}

Esperas entre intentos

attempt 0  →  wait Retry-After + jitter
attempt 1  →  wait (Retry-After + jitter) × 2
attempt 2  →  wait (Retry-After + jitter) × 4
...
attempt 5  →  give up, log Fluyio-Request-Id, alert

Limita los reintentos y devuelve el trabajo a una cola o a revisión si se agotan. Los ejemplos reintentan únicamente 429.

No hay un endpoint de carga masiva. Cada creación y cada búsqueda previa consumen peticiones. Una capacidad teórica de 600 por minuto equivale a 36.000 peticiones por hora; el ritmo real depende de latencia, concurrencia, errores y operaciones adicionales.

Usa una cola para absorber picos y mantén su consumo por debajo de los límites. limit=100 reduce las peticiones de lectura frente al valor predeterminado de 25. Consulta la guía de sincronización.

Otros errores

Estado	Qué hacer
`429`	Espera `Retry-After` antes del siguiente intento.
`403 profile_limit`	Revisa el plan y los perfiles; repetir la petición no resuelve el límite.
`403 missing_scope`	Revisa los permisos de la clave.
`403 test_mode_unavailable`	El modo test no está disponible.
`5xx`	Distingue lectura de escritura. Una escritura con resultado incierto requiere comprobar el estado, no repetirla automáticamente.

Si una operación ya reservada con Idempotency-Key devuelve un 5xx o tiene resultado incierto, conserva la reserva durante 24 horas. Reutilizarla no reejecuta automáticamente la escritura; no cambies de clave para forzarla. Consulta idempotencia.

Un 503 idempotency_unavailable indica que no se inició la operación; no garantiza una reserva creada. Reintenta la misma operación con la misma clave, sin generar otra para eludir la protección.

Más capacidad y seguimiento

Si necesitas otro volumen, describe el caso de uso a [email protected]. Monitoriza peticiones restantes, número de 429 y tiempo de espera. Consulta también errores y paginación.

Límites de peticiones