Limites de taxa
Quantas requisições você pode enviar, o que acontece se passar disso e outros limites que vale conhecer.
Os limites protegem todo mundo que divide o serviço. Os valores padrão são folgados para o uso normal; se você bater em um, a resposta diz exatamente quanto esperar.
Resumo
| Limite | Padrão | Quando você atinge |
|---|---|---|
Escritas por conta (createTask, retry, uploads …) | 1.000 a cada 10 segundos | 429 com Retry-After |
Leituras por conta (recordInfo, models, jobs, quote …) | 1.000 a cada 10 segundos | 429 com Retry-After |
| Tickets de upload | 1.000 a cada 10 segundos, além das escritas | 429 com Retry-After |
Relatório de uso (/api/v1/usage) | 30 por minuto por conta | 429 com Retry-After |
| Biblioteca de assets | 60 leituras e 30 salvamentos por minuto, além de um número diário de novos assets | 429 com Retry-After |
| Qualquer requisição antes de checar a chave | 6.000 por minuto por rede | 429 |
| Corpo da requisição | 2 MiB de JSON | 413 |
| Saldo | O que houver na sua conta | 40201 |
| Limites de gasto por chave | Nenhum, a menos que você defina | 40202 |
Os limites contam por conta, não por chave — criar mais chaves não aumenta nada.
Cabeçalhos de resposta
| Cabeçalho | Significado |
|---|---|
X-RateLimit-Limit | Sua cota na janela atual |
X-RateLimit-Remaining | Quanto ainda resta — vem também nas respostas de sucesso, para você desacelerar antes |
Retry-After | Em um 429: segundos de espera antes de tentar de novo |
Os números acima são padrões e podem mudar; confie nos cabeçalhos em vez de fixá-los no código.
Como é um limite
{ "code": 429, "msg": "Too many requests. Retry in a moment", "request_id": "req_…" }Uma requisição acima do limite é recusada na hora — não vai para fila — e não custa nada.
Como lidar
- Espere pelo menos
Retry-Aftersegundos e tente de novo. Acrescente um pouco de aleatoriedade para que vários clientes não voltem no mesmo instante. - Ao repetir
createTask, envie o mesmoIdempotency-Key(Idempotência). - Consulte com calma: a cada poucos segundos para imagens, a cada 10–15 segundos para vídeo. Melhor ainda, use webhooks — eles não gastam nenhuma requisição.
Muitas tarefas ao mesmo tempo
Os limites de taxa controlam a velocidade com que você envia requisições, não quantas tarefas rodam ao mesmo tempo. Você pode ter muitas tarefas em andamento; vídeos longos só demoram mais. Se precisar disparar milhares de tarefas, espalhe os envios e deixe os webhooks trazerem os resultados.
Precisa de uma cota maior para um lançamento ou um lote grande? Fale com a gente informando o volume esperado.