Rate Limits

Entenda os limites de requisições da API e como monitorá-los.

Como Funciona

A API aplica rate limiting em duas camadas: por API Key e por endereço IP. Isso garante uso justo e protege contra abusos.

Limite	Padrão	Customizável	Escopo
Por API Key	`60 req/min`	Sim, ao criar a chave	Cada chave individual
Por IP	`100 req/min`	Não	Todos os IPs

Resposta de Rate Limit

Quando o limite é excedido, a API retorna status 429 Too Many Requests com informações sobre quando tentar novamente.

429 — Rate limit excedido

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit excedido. Máximo: 60 req/min. Tente novamente em 45s.",
  "retryAfter": 45
}

Headers de Rate Limit

Toda resposta inclui headers informativos sobre o estado do rate limit:

Header	Descrição
`X-RateLimit-Limit`	Limite total da janela
`X-RateLimit-Remaining`	Requisições restantes na janela
`X-RateLimit-Reset`	Timestamp Unix de quando o limite reseta

Boas Práticas

Implemente retry com backoff exponencial em caso de 429
Use caching para reduzir chamadas repetidas
Crie chaves separadas para diferentes serviços e ambientes
Monitore o campo lastUsedAt para identificar chaves inativas

Customizar limite

Crie uma nova API Key com rateLimit customizado para limites maiores. Exemplo: "rateLimit": 300 para 300 req/min.