Rate Limiting

Visao Geral

O rate limiting protege sua organizacao contra custos descontrolados, abuso e picos de trafego acidentais. O Floopy aplica limites em dois niveis — no nivel do gateway e por chave de API — para que voce tenha tanto uma rede de seguranca global quanto controle granular sobre consumidores individuais.

Quando uma requisicao excede o limite configurado, o gateway retorna uma resposta 429 Too Many Requests. A resposta inclui um header Retry-After indicando quando o cliente pode tentar novamente.

Rate Limiting no Nivel do Gateway

Os limites no nivel do gateway se aplicam a todo o trafego que chega ao gateway do Floopy:

• Requisicoes nao autenticadas sao limitadas por endereco IP. Isso previne abuso anonimo e varreduras.
• Requisicoes autenticadas sao limitadas por organizacao com um limite configuravel de requisicoes por minuto (RPM).

O limite de RPM da organizacao funciona como um teto para todas as chaves de API. Mesmo que chaves individuais tenham limites mais altos, o trafego total da organizacao nao pode exceder esse valor.

Voce pode configurar o RPM da organizacao em Settings > Organization.

Rate Limiting por Chave de API

Cada chave de API pode ter seu proprio limite, independente do limite do gateway. Isso e util quando voce tem multiplos consumidores com diferentes niveis de confianca ou expectativas de uso.

Para definir um limite por chave:

1. Va em Settings > API Keys.
2. Selecione a chave que deseja configurar.
3. Defina o valor de requisicoes por minuto.

Uma requisicao e bloqueada se exceder o limite da chave ou o limite da organizacao, o que for atingido primeiro.

Como os Limites Sao Aplicados

O Floopy usa um algoritmo de janela deslizante (sliding window) apoiado pelo Redis. Diferente de janelas fixas (que reiniciam no inicio de cada minuto), janelas deslizantes distribuem o limite uniformemente ao longo do tempo e previnem rajadas de trafego nos limites das janelas.

Essa abordagem e consistente entre instancias do gateway escaladas horizontalmente — todos os nos compartilham o mesmo estado de rate limit, entao um cliente nao pode burlar os limites acessando servidores diferentes.

Metricas do Dashboard

A secao Rate Limiting do dashboard mostra:

• Eventos de rate limit ao longo do tempo — um grafico de quantas requisicoes foram limitadas por periodo.
• Usuarios mais limitados — quais chaves de API ou enderecos IP estao atingindo os limites com mais frequencia.

Use essas metricas para decidir se deve aumentar os limites para consumidores legitimos ou investigar possivel abuso.

Politicas de Rate Limit Customizadas

Voce pode definir uma politica de rate limit customizada por requisicao usando o header floopy-ratelimit-policy. Isso sobrescreve os limites padrao configurados para a chave de API.

O formato do header e:

<limit>;w=<window>;u=<unit>;s=<segment>

Por exemplo, 100;w=60;u=request;s=global significa 100 requisicoes por 60 segundos entre todos os usuarios compartilhando esta politica.

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://api.floopy.ai/v1",
  apiKey: process.env.FLOOPY_API_KEY,
});

const response = await client.chat.completions.create(
  {
    model: "gpt-4o",
    messages: [{ role: "user", content: "Hello" }],
  },
  {
    headers: {
      "floopy-ratelimit-policy": "100;w=60;u=request;s=global",
    },
  },
);

console.log(response.choices[0].message.content);

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.floopy.ai/v1",
    api_key=os.environ["FLOOPY_API_KEY"],
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "floopy-ratelimit-policy": "100;w=60;u=request;s=global",
    },
)

print(response.choices[0].message.content)

curl https://api.floopy.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLOOPY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "floopy-ratelimit-policy: 100;w=60;u=request;s=global" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Boas Praticas

• Comece generoso, aperte depois. Defina limites iniciais acima do seu pico de trafego esperado e reduza conforme voce entende seus padroes de uso.
• Use limites por chave para consumidores externos. Se voce distribui chaves de API para terceiros, limites por chave evitam que um unico consumidor monopolize sua cota.
• Monitore antes de aplicar. Revise o dashboard de rate limiting por alguns dias antes de reduzir limites para evitar interromper trafego legitimo.
• Combine com caching. Respostas em cache nao contam para os limites de rate. Habilitar caching efetivamente aumenta o throughput que seus consumidores experimentam.