# 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

```json title="429 Too Many Requests"
{ "code": "RATE_LIMIT_EXCEEDED" }
```

O header `Retry-After` diz quantos segundos esperar. Respeite: repetir na hora só gasta a próxima janela.

```js
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.

```bash
curl https://api.cut.pro/api/v1/renders/limits \
  -H "X-Api-Key: $CUTPRO_API_KEY"
```

```json title="200 OK"
{
  "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.