Rate Limits

Limites de taxa da API Polar. TPM e RPM por tier, headers de rate limit e estratégia de retry com backoff exponencial.

Visão Geral

A API Polar implementa rate limiting para garantir uso justo e estabilidade do serviço. Os limites são aplicados por API key e variam conforme o tier (plano) da conta.

Limites por Tier

TPM (Tokens Por Minuto)

Tier	TPM	Descrição
Free	10.000	Contas com créditos gratuitos
Pro	100.000	Contas com saldo ativo
Enterprise	1.000.000	Contratos enterprise

RPM (Requisições Por Minuto)

Tier	RPM	Descrição
Free	20	Contas com créditos gratuitos
Pro	200	Contas com saldo ativo
Enterprise	2.000	Contratos enterprise

Limites por Endpoint

Além dos limites globais, alguns endpoints possuem limites específicos:

Endpoint	Free RPM	Pro RPM	Enterprise RPM
`/v1/chat/completions`	20	200	2.000
`/v1/embeddings`	50	500	5.000
`/v1/jurisia/*`	10	100	1.000
`/v1/urso-eco/stream`	2	10	50
`/v1/batch/*`	5	50	500

Headers de Rate Limit

Toda resposta da API inclui headers informativos sobre o rate limit:

Header	Tipo	Descrição
`X-RateLimit-Limit`	integer	Limite máximo de requisições no período
`X-RateLimit-Remaining`	integer	Requisições restantes no período
`X-RateLimit-Reset`	integer	Timestamp Unix de quando o limite reseta
`X-RateLimit-Limit-Tokens`	integer	Limite máximo de tokens no período
`X-RateLimit-Remaining-Tokens`	integer	Tokens restantes no período

Exemplo de Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 1710000060
X-RateLimit-Limit-Tokens: 100000
X-RateLimit-Remaining-Tokens: 98500

Resposta 429 (Rate Limited)

Quando o limite é excedido, a API retorna status 429:

{
  "error": {
    "message": "Rate limit excedido. Máximo de 200 requisições por minuto.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

O header Retry-After indica em quantos segundos tentar novamente:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710000060

Estratégia de Retry

Backoff Exponencial com Jitter

Implemente retry com backoff exponencial para lidar com rate limits:

import time
import random
import requests

def make_request_with_retry(url, headers, json_data, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_data)

        if response.status_code == 429:
            # Obter tempo de espera do header Retry-After
            retry_after = int(response.headers.get("Retry-After", 1))

            # Backoff exponencial: 1s, 2s, 4s, 8s, 16s
            base_delay = min(retry_after, 2 ** attempt)

            # Adicionar jitter (aleatoriedade)
            jitter = random.uniform(0, base_delay * 0.5)
            delay = base_delay + jitter

            print(f"Rate limited. Aguardando {delay:.1f}s (tentativa {attempt + 1})")
            time.sleep(delay)
            continue

        return response

    raise Exception(f"Falha após {max_retries} tentativas")

# Uso
response = make_request_with_retry(
    "https://api.polarai.com.br/v1/chat/completions",
    headers={"Authorization": "Bearer pk-sua-chave-aqui"},
    json_data={
        "model": "urso-mabe",
        "messages": [{"role": "user", "content": "Olá!"}]
    }
)

TypeScript

async function makeRequestWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 5
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "1");
      const baseDelay = Math.min(retryAfter, Math.pow(2, attempt));
      const jitter = Math.random() * baseDelay * 0.5;
      const delay = baseDelay + jitter;

      console.log(`Rate limited. Waiting ${delay.toFixed(1)}s (attempt ${attempt + 1})`);
      await new Promise(resolve => setTimeout(resolve, delay * 1000));
      continue;
    }

    return response;
  }

  throw new Error(`Failed after ${maxRetries} attempts`);
}

Dicas para Otimizar Uso

Batch API: Use o endpoint de batch para processar muitas requisições com limites separados e 50% de desconto.
Cache: Armazene resultados em cache quando possível para evitar requisições duplicadas.
Streaming: Use streaming para respostas longas, pois a requisição conta como uma única RPM.
Modelos menores: Use urso-mabe para tarefas simples, economizando TPM.
Monitoramento: Acompanhe os headers de rate limit para ajustar a taxa de envio antes de ser limitado.

Solicitar Aumento de Limite

Para limites maiores, entre em contato:

Pro: Upgrade disponível automaticamente ao adicionar créditos
Enterprise: Contate vendas em enterprise@polar-ai.com para limites personalizados

On this page