Limites de requisição
600 requisições por minuto por chave, os headers que mostram quanto sobrou e como reagir ao 429.
| Limite | Valor | Janela |
|---|---|---|
| Requisições por chave | 600 | 60 segundos fixos |
POST /clips/info | 10 | 60 segundos fixos |
POST /clips/info tem limite próprio porque cada chamada consulta a plataforma de origem do vídeo.
Headers
Toda resposta traz o estado da janela atual, para você desacelerar antes de ser cortado:
| Header | Descrição |
|---|---|
X-RateLimit-Limit | O teto da janela (600) |
X-RateLimit-Remaining | Requisições que ainda cabem nesta janela |
X-RateLimit-Reset | Quando a janela reinicia, em segundos Unix |
Ao passar do limite
{ "code": "RATE_LIMIT_EXCEEDED" }O header Retry-After diz quantos segundos esperar. Respeite: repetir na hora só gasta a próxima janela.
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 também vem com Retry-After. Trate do mesmo jeito.
Limites de concorrência
Alguns limites não são de requisição, são de quantos jobs rodam ao mesmo tempo. Eles também respondem 429, com outro code:
| Code | Quando | O que fazer |
|---|---|---|
TOO_MANY_PENDING_CLIPS | Muitas clipagens na fila do workspace | Espere uma terminar. |
BATCH_ALREADY_RUNNING | Já existe um template sendo aplicado em lote na conta | Espere o lote terminar. |
TOO_MANY_RUNNING | Muitas gerações com IA rodando ao mesmo tempo | Espere uma terminar. |
Renders
O plano define quantos renders rodam ao mesmo tempo (max_concurrent). Os que passam disso esperam na fila e aparecem em queued_count. GET /renders/limits mostra também a resolução máxima, a marca d'água e por quantas horas o MP4 fica guardado.
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 um job a cada 5 a 10 segundos é o padrão esperado. Com 600 requisições por minuto, dá para acompanhar 50 jobs ao mesmo tempo consultando a cada 5 segundos.