Rate limit & concorrência

A API v1 aplica dois limites independentes: um de requisições por minuto e outro de tasks em andamento simultâneas. Ambos retornam HTTP 429, mas com códigos distintos.

Rate limit — 60 req/min

Cada token é limitado a 60 requisições por minuto. Ao estourar, a resposta é 429 RATE_LIMITED, acompanhada do header Retry-After (segundos a aguardar antes de tentar de novo).

HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "..." }
}

Concorrência — 20 tasks simultâneas

Independente do rate limit, cada usuário pode ter no máximo 20 tasks de geração em andamento ao mesmo tempo. A criação que ultrapassa esse teto retorna 429 MAX_CONCURRENT_TASKS:

{
  "success": false,
  "error": { "code": "MAX_CONCURRENT_TASKS", "message": "..." }
}

Diferente do rate limit, este não é resolvido apenas esperando alguns segundos: é preciso que tasks em curso atinjam estado terminal (completed/failed). Acompanhe-as em Ciclo de vida da task.

Como reagir

• RATE_LIMITED: respeite o Retry-After e implemente backoff exponencial nas tentativas seguintes.
• MAX_CONCURRENT_TASKS: pare de enfileirar novas tasks e aguarde as atuais concluírem (via polling ou webhook) antes de criar mais.
• Em ambos os casos, evite retry imediato em loop apertado.