Límites de solicitudes
600 solicitudes por minuto por clave, los headers que muestran cuántas quedan y cómo reaccionar al 429.
| Límite | Valor | Ventana |
|---|---|---|
| Solicitudes por clave | 600 | 60 segundos fijos |
POST /clips/info | 10 | 60 segundos fijos |
POST /clips/info tiene un límite propio porque cada llamada consulta la plataforma de origen del video.
Headers
Toda respuesta trae el estado de la ventana actual, para que desacelres antes de que te corten:
| Header | Descripción |
|---|---|
X-RateLimit-Limit | El tope de la ventana (600) |
X-RateLimit-Remaining | Solicitudes que aún caben en esta ventana |
X-RateLimit-Reset | Cuándo se reinicia la ventana, en segundos Unix |
Al pasar el límite
{ "code": "RATE_LIMIT_EXCEEDED" }El header Retry-After dice cuántos segundos esperar. Respétalo: repetir al instante solo gasta la próxima ventana.
async function call(url, init) {
const response = await fetch(url, init);
if (response.status !== 429) return response;
const seconds = Number(response.headers.get("Retry-After") ?? 1);
await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
return call(url, init);
}503 SERVICE_UNAVAILABLE también viene con Retry-After. Trátalo igual.
Límites de concurrencia
Algunos límites no son de solicitudes, sino de cuántos jobs corren al mismo tiempo. También responden 429, con otro code:
| Code | Cuándo | Qué hacer |
|---|---|---|
TOO_MANY_PENDING_CLIPS | Demasiados clippings en la cola del workspace | Espera a que termine uno. |
BATCH_ALREADY_RUNNING | Ya hay una plantilla aplicándose en lote en la cuenta | Espera a que termine el lote. |
TOO_MANY_RUNNING | Demasiadas generaciones con IA corriendo al mismo tiempo | Espera a que termine una. |
Renders
El plan define cuántos renders corren al mismo tiempo (max_concurrent). Los que superan ese número esperan en la cola y aparecen en queued_count. GET /renders/limits muestra también la resolución máxima, la marca de agua y por cuántas horas se guarda el MP4.
curl https://api.cut.pro/api/v1/renders/limits \
-H "X-Api-Key: $CUTPRO_API_KEY"{
"usage": { "active_count": 2, "queued_count": 1, "total_pending": 3, "max_concurrent": 5 },
"plan": {
"video_quality": "1080p",
"watermark": false,
"priority_processing": true,
"max_concurrent_renders": 5,
"render_expiry_hours": 168
}
}Polling
Consultar un job cada 5 a 10 segundos es el patrón esperado. Con 600 solicitudes por minuto, puedes seguir 50 jobs al mismo tiempo consultando cada 5 segundos.