{"title":"Limites de taxa e cotas","slug":"rate-limits","category":"api","summary":"Política de limites de taxa da API do Synapse — cabeçalho Bearer (ilimitado), ?key= (60/min), endpoints públicos.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":381,"read_minutes":2,"llm_context":"Mind Key (Authorization: Bearer header) → NO rate limit\nMind Key (?key= query param) → 60 req/min per IP\nJWT (Authorization: Bearer header) → NO rate limit\nPublic endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit\nRate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After\nRecommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.\n","lang":"pt","translated":true,"requested_lang":"pt","content_markdown":"\n# Limites de taxa e cotas\n\nO Synapse tem uma política de limite de taxa simples e previsível, projetada\npara evitar abuso sem atrapalhar o uso legítimo.\n\n## Política de limite de taxa\n\n| Método de auth | Limite | Escopo |\n|----------------|--------|--------|\n| Mind Key (`Authorization: Bearer`) | **Nenhum** | Por mind |\n| Mind Key (`?key=`) | 60 req/min | Por IP |\n| JWT (`Authorization: Bearer`) | **Nenhum** | Por usuário |\n| Endpoints públicos | **Nenhum** | Global |\n\n> [!TIP]\n> **Sempre use o cabeçalho `Authorization: Bearer`** quando possível. Ele não\n> tem limite de taxa. Use `?key=` apenas para ferramentas que não conseguem\n> definir cabeçalhos personalizados.\n\n## Cabeçalhos de limite de taxa\n\nQuando você usa auth via `?key=`, as respostas incluem cabeçalhos de limite:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nQuando você excede o limite:\n\n```\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\n## Quando você atinge um limite de taxa\n\nSe você recebe um 429:\n\n1. **Mude para o cabeçalho Authorization** (recomendado):\n ```bash\n # Don't: ?key=YOUR_MIND_KEY (60/min limit)\n curl \".../memory/recall?key=YOUR_MIND_KEY\"\n \n # Do: Authorization header (unlimited)\n curl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n ```\n\n2. **Ou aguarde `Retry-After` segundos** e tente novamente.\n\n## Por que o limite de ?key= existe\n\nO parâmetro de consulta `?key=` é conveniente para ferramentas somente-URL\n(navegadores, comandos `open`), mas tem implicações de segurança e desempenho:\n\n- **Segurança:** Parâmetros de consulta são registrados em logs de acesso do\n servidor, histórico do navegador e cabeçalhos Referer. Limitar o uso reduz a\n exposição.\n- **Desempenho:** Auth por parâmetro de consulta requer um limitador de taxa\n baseado em IP (lookup Redis por requisição), o que adiciona latência. Auth\n por cabeçalho pula isso.\n- **Prevenção de abuso:** Uma URL `?key=` vazada poderia ser compartilhada e\n bombardeada. O limite por IP contém o raio de explosão.\n\n## Padrões recomendados\n\n### Agentes LLM\n\n```python\n# Always use header auth\nheaders = {\"Authorization\": f\"Bearer {MIND_KEY}\"}\nresponse = requests.get(f\"{URL}/memory/recall\", headers=headers)\n```\n\n### Ferramentas baseadas em navegador\n\nSe sua ferramenta só consegue abrir URLs:\n\n```bash\n# OK for occasional use (under 60/min)\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# For frequent use, switch to a tool that supports headers\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n### Servidor MCP\n\nServidores MCP sempre usam auth por cabeçalho via variável de ambiente\n`SYNAPSE_MIND_KEY` — nenhum limite de taxa se aplica.\n\n### Importações em massa\n\nPara operações em massa (ex.: importar 1000 memórias), sempre use auth por\ncabeçalho. Importações em massa via `?key=` atingirão o limite de taxa em menos\nde 1 minuto.\n\n## Cotas (nível de mind)\n\nAtualmente não há cotas por mind em tamanho de armazenamento ou contagem de\nmemórias. Todos os limites são em nível de auth/IP, não de dados. Isso pode\nmudar no futuro para justiça multi-tenant.\n\n## Monitorando seu uso\n\n```bash\n# Check your current rate limit status (with ?key= auth)\ncurl -i \"https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY\" | grep -i ratelimit\n\n# Output:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840\n```\n\n## Próximos passos\n\n- [Autenticação](/docs/getting-started/authentication)\n- [Erros e tratamento de erros](/docs/api/errors)\n","content_html":"

Limites de taxa e cotas

\n

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

\n

Política de limite de taxa

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Método de authLimiteEscopo
Mind Key (Authorization: Bearer)NenhumPor mind
Mind Key (?key=)60 req/minPor IP
JWT (Authorization: Bearer)NenhumPor usuário
Endpoints públicosNenhumGlobal
\n
**Sempre use o cabeçalho `Authorization: Bearer`** quando possível. Ele não\ntem limite de taxa. Use `?key=` apenas para ferramentas que não conseguem\ndefinir cabeçalhos personalizados.

Cabeçalhos de limite de taxa

\n

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840

Quando você excede o limite:

\n
HTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n  "statusCode": 429,\n  "error": "Too Many Requests",\n  "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}

Quando você atinge um limite de taxa

\n

Se você recebe um 429:

\n
    \n

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

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

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

    \n
    3. \n
\n

Por que o limite de ?key= existe

\n

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

\n\n

Padrões recomendados

\n

Agentes LLM

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

Ferramentas baseadas em navegador

\n

Se sua ferramenta só consegue abrir URLs:

\n
# OK for occasional use (under 60/min)\nopen "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"\n\n# For frequent use, switch to a tool that supports headers\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

Servidor MCP

\n

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

\n

Importações em massa

\n

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

\n

Cotas (nível de mind)

\n

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

\n

Monitorando seu uso

\n
# Check your current rate limit status (with ?key= auth)\ncurl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit\n\n# Output:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840

Próximos passos

\n\n","urls":{"html":"/docs/api/rate-limits","text":"/docs/api/rate-limits?format=text","json":"/docs/api/rate-limits?format=json","llm":"/docs/api/rate-limits?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}