Rate limiting

A API pública aplica limites por API key, por projeto e por IP para proteger a infraestrutura.

Limites por API key / projeto

Limite	Valor padrão	Escopo	Variável de ambiente
Requisições/minuto	60	Por API key	`API_RATE_LIMIT_PER_MINUTE`
Requisições/dia	1.000	Por projeto (todas as chaves)	`API_DAILY_LIMIT`
Jobs simultâneos	2	Por projeto (`queued` + `processing`)	`API_MAX_CONCURRENT_JOBS`

Jobs em status queued ou processing contam para o limite de concorrência. Aguarde completed ou failed antes de enfileirar novos downloads.

Headers de resposta (rotas autenticadas)

Em requisições autenticadas bem-sucedidas, a API retorna:

Header	Significado
`X-RateLimit-Limit`	Máximo na janela atual (por minuto)
`X-RateLimit-Remaining`	Requisições restantes na janela
`X-RateLimit-Reset`	Unix timestamp absoluto do início do próximo minuto

X-RateLimit-Reset é um epoch timestamp — não segundos restantes. Em respostas 429 por rate limit da API key, esses headers não são enviados.

Códigos de erro `429`

Código	Situação
`rate_limit_exceeded`	Mais de 60 req/min na mesma chave
`daily_limit_exceeded`	Cota diária do projeto esgotada
`concurrency_limit_exceeded`	Mais de 2 jobs de download simultâneos

Corpo típico:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests per minute.",
    "request_id": "req_abc123"
  }
}

Limites globais por IP

Antes do router /v1, a infraestrutura aplica limites adicionais por IP:

Limiter	Janela	Limite
Global	60 s	100 req/IP
Burst	5 s	30 req/IP

Formato de erro diferente (sem request_id):

{
  "error": {
    "code": "error.api.rate_limited",
    "message": "Muitas requisições. Aguarde."
  }
}

Headers seguem o padrão draft-6 (Ratelimit-Limit, Ratelimit-Remaining, etc.). Em integrações server-to-server normais, o limite por API key é o que importa. Os limites por IP afetam principalmente tráfego sem autenticação ou abusivo.

Boas práticas

Implemente backoff exponencial em 429 e 5xx
Use GET /jobs/{jobId} com intervalo de 2–5 s — não faça polling agressivo em /media/resolve
Registre request_id nos logs para suporte
Use fila no seu backend para respeitar o limite de 2 jobs simultâneos

Veja também: Polling e retentativas · Boas práticas

Introdução

Mídia

Endpoints

Limites por API key / projeto

Headers de resposta (rotas autenticadas)

Códigos de erro `429`

Limites globais por IP

Boas práticas

​Limites por API key / projeto

​Headers de resposta (rotas autenticadas)

​Códigos de erro 429

​Limites globais por IP

​Boas práticas

Limites por API key / projeto

Headers de resposta (rotas autenticadas)

Códigos de erro `429`

Limites globais por IP

Boas práticas