Como Definir Limites de Taxa em Requisições da API Perplexity

Gerenciar o volume de requisições de API é essencial ao integrar o Perplexity em seus aplicativos. Sem limites de taxa, seu código pode sobrecarregar o servidor da API, gerar erros HTTP 429 Too Many Requests ou exceder sua cota de assinatura inesperadamente. Este artigo explica como configurar limites de taxa em requisições da API Perplexity usando as melhores práticas para Python, JavaScript e cabeçalhos HTTP. Você aprenderá a implementar throttling no lado do cliente, ler limites do servidor a partir dos cabeçalhos de resposta e lidar com backoff de forma adequada.

Por que os Limites de Taxa são Importantes para a API Perplexity

A API Perplexity impõe limites de taxa para proteger os recursos do servidor e garantir uso justo entre todos os clientes. Exceder esses limites resulta em respostas HTTP 429. Seu aplicativo deve respeitar esses limites para manter um serviço confiável e evitar retentativas desnecessárias que desperdiçam tempo e cota.

Os limites de taxa são definidos por chave de API e dependem do seu plano de assinatura. O plano Free permite 5 requisições por segundo. O plano Pro permite 10 requisições por segundo. Os limites se aplicam a todos os endpoints em api.perplexity.ai e todos os subdomínios. A API retorna o limite atual e as requisições restantes nos cabeçalhos de resposta chamados X-RateLimit-Limit e X-RateLimit-Remaining.

Entendendo o Cabeçalho Retry-After

Quando a API retorna 429, ela inclui um cabeçalho Retry-After com um valor numérico em segundos. Esse valor informa ao seu cliente quanto tempo esperar antes de enviar a próxima requisição. Ignorar esse cabeçalho pode levar a erros 429 repetidos e possível bloqueio temporário da sua chave de API.

Passos para Definir Limites de Taxa no Seu Código

Você pode implementar limites de taxa no lado do cliente usando duas estratégias complementares: ler os cabeçalhos do servidor e limitar sua própria taxa de requisições. Os passos a seguir mostram como aplicar ambas as abordagens em Python e JavaScript.

Método 1: Limitar Requisições com um Token Bucket (Python)

1. Instale a biblioteca requests
   Abra seu terminal e execute pip install requests se você ainda não a tiver. Esta biblioteca lida com chamadas HTTP e cabeçalhos.
2. Crie uma classe de limitador de taxa
   Defina uma classe que armazene o máximo de requisições por segundo e o timestamp da última requisição. Em cada chamada, calcule o intervalo mínimo entre requisições como 1.0 / max_rps. Use time.sleep() para pausar se o intervalo não tiver passado.
3. Envie requisições através do limitador
   Encapsule cada chamada de API em um método que chame o limitador antes de enviar. Exemplo: limiter.wait() e depois requests.post(url, headers=headers, json=payload).
4. Analise os cabeçalhos de resposta
   Após uma resposta bem-sucedida, leia response.headers.get('X-RateLimit-Remaining') e response.headers.get('X-RateLimit-Reset'). Se remaining for 0, pause até o timestamp de reset.
5. Trate respostas 429
   Se o status da resposta for 429, leia response.headers.get('Retry-After') e durma por esse número de segundos. Em seguida, tente a mesma requisição novamente uma vez.

Método 2: Use um Semáforo em JavaScript (Node.js)

1. Instale o pacote bottleneck
   Execute npm install bottleneck na pasta do seu projeto. O Bottleneck fornece um limitador de taxa configurável que funciona com promises.
2. Crie uma instância do limitador
   Escreva const limiter = new Bottleneck({ minTime: 100, maxConcurrent: 1 }); O valor minTime de 100 milissegundos equivale a 10 requisições por segundo.
3. Encapsule sua função de chamada de API
   Passe sua chamada fetch ou axios para limiter.schedule(fn). Isso garante que a chamada aguarde a janela de limite de taxa.
4. Inspecione os cabeçalhos de resposta
   Dentro da função agendada, verifique o objeto de resposta para headers['x-ratelimit-remaining']. Se o valor for 0, defina uma flag para pular requisições adicionais durante a duração de headers['x-ratelimit-reset'].

Problemas Comuns ao Definir Limites de Taxa

Cabeçalho Retry-After Ausente

Alguns endpoints da API podem retornar 429 sem um cabeçalho Retry-After. Nesse caso, use um backoff padrão de 5 segundos. Implemente backoff exponencial dobrando o tempo de espera em respostas 429 consecutivas até um máximo de 60 segundos.

Limite de Taxa é Reiniciado no Meio da Requisição

Se seu cliente enviar muitas requisições no exato segundo em que o limite é reiniciado, você ainda pode atingir o limite porque o servidor conta as requisições em uma janela contínua. Para evitar isso, reduza sua taxa de throttling para 80% do limite anunciado. Para o plano Pro, faça throttling a 8 RPS em vez de 10.

Requisições Concorrentes Excedem o Limite

Ao usar múltiplas threads ou processos workers, cada worker deve compartilhar o mesmo estado de limite de taxa. Use um armazenamento centralizado como Redis ou um bloqueio de arquivo para coordenar o tempo das requisições entre workers. Sem coordenação, cada worker pensa independentemente que pode enviar 10 RPS, levando a erros 429.

Planos da API Perplexity: Comparação de Limites de Taxa

Item	Plano Free	Plano Pro
Requisições por segundo	5	10
Cota mensal	1.000 requisições	10.000 requisições
Cabeçalhos de resposta	X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset	Mesmos cabeçalhos mais Retry-After em 429
Permissão de rajada (burst)	Nenhuma	Até 20 requisições em 2 segundos
Throttling recomendado no cliente	4 RPS	8 RPS

Você agora aprendeu a definir limites de taxa para a API Perplexity usando throttling no lado do cliente e análise de cabeçalhos do servidor. Aplique o padrão token bucket em Python ou a biblioteca bottleneck em JavaScript para permanecer dentro dos limites do seu plano. Para sistemas de produção, adicione coordenação centralizada com Redis para lidar com múltiplos workers sem atingir erros 429. Monitore o cabeçalho X-RateLimit-Remaining após cada resposta para ajustar seu throttling dinamicamente.