Limites de taxa e cotas

O Synapse tem uma política de limite de taxa simples e previsível, projetada para evitar abuso sem atrapalhar o uso legítimo.

Política de limite de taxa

Cabeçalhos de limite de taxa

Quando você usa auth via ?key=, as respostas incluem cabeçalhos de limite:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1782567840

Quando você excede o limite:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
Content-Type: application/json

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Use Authorization header for unlimited access."
}

Quando você atinge um limite de taxa

Se você recebe um 429:

1. Mude para o cabeçalho Authorization (recomendado):

   # Don't: ?key=YOUR_MIND_KEY (60/min limit)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # Do: Authorization header (unlimited)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

2. Ou aguarde Retry-After segundos e tente novamente.

Por que o limite de ?key= existe

O parâmetro de consulta ?key= é conveniente para ferramentas somente-URL (navegadores, comandos open), mas tem implicações de segurança e desempenho:

• Segurança: Parâmetros de consulta são registrados em logs de acesso do servidor, histórico do navegador e cabeçalhos Referer. Limitar o uso reduz a exposição.
• Desempenho: Auth por parâmetro de consulta requer um limitador de taxa baseado em IP (lookup Redis por requisição), o que adiciona latência. Auth por cabeçalho pula isso.
• Prevenção de abuso: Uma URL ?key= vazada poderia ser compartilhada e bombardeada. O limite por IP contém o raio de explosão.

Padrões recomendados

Agentes LLM

# Always use header auth
headers = {"Authorization": f"Bearer {MIND_KEY}"}
response = requests.get(f"{URL}/memory/recall", headers=headers)

Ferramentas baseadas em navegador

Se sua ferramenta só consegue abrir URLs:

# OK for occasional use (under 60/min)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# For frequent use, switch to a tool that supports headers
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

Servidor MCP

Servidores MCP sempre usam auth por cabeçalho via variável de ambiente SYNAPSE_MIND_KEY — nenhum limite de taxa se aplica.

Importações em massa

Para operações em massa (ex.: importar 1000 memórias), sempre use auth por cabeçalho. Importações em massa via ?key= atingirão o limite de taxa em menos de 1 minuto.

Cotas (nível de mind)

Atualmente não há cotas por mind em tamanho de armazenamento ou contagem de memórias. Todos os limites são em nível de auth/IP, não de dados. Isso pode mudar no futuro para justiça multi-tenant.

Monitorando seu uso

# Check your current rate limit status (with ?key= auth)
curl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit

# Output:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 58
# X-RateLimit-Reset: 1782567840

Próximos passos

• Autenticação
• Erros e tratamento de erros