{"title":"Límites de frecuencia y cuotas","slug":"rate-limits","category":"api","summary":"Políticas de límites de frecuencia de la API de Synapse — cabecera 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":389,"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":"es","translated":true,"requested_lang":"es","content_markdown":"\n# Límites de frecuencia y cuotas\n\nSynapse tiene una política de límites de frecuencia simple y predecible,\ndiseñada para prevenir el abuso sin estorbar el uso legítimo.\n\n## Política de límites de frecuencia\n\n| Método de auth | Límite | Ámbito |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **Ninguno** | Por mind |\n| Mind Key (`?key=`) | 60 req/min | Por IP |\n| JWT (`Authorization: Bearer`) | **Ninguno** | Por usuario |\n| Endpoints públicos | **Ninguno** | Global |\n\n> [!TIP]\n> **Use siempre la cabecera `Authorization: Bearer`** cuando sea posible. No\n> tiene límite de frecuencia. Use `?key=` solo para herramientas que no puedan\n> establecer cabeceras personalizadas.\n\n## Cabeceras de límite de frecuencia\n\nCuando use auth con `?key=`, las respuestas incluyen cabeceras de límite:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nCuando supere el límite:\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## Cuando alcanza un límite de frecuencia\n\nSi obtiene un 429:\n\n1. **Cambie a la cabecera 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. **O espere `Retry-After` segundos** y reintente.\n\n## Por qué existe el límite de ?key=\n\nEl parámetro de consulta `?key=` es conveniente para herramientas que solo usan\nURLs (navegadores, comandos `open`), pero tiene implicaciones de seguridad y\nrendimiento:\n\n- **Seguridad:** Los parámetros de consulta se registran en logs de acceso del\n servidor, historial del navegador y cabeceras Referer. Limitar su uso reduce\n la exposición.\n- **Rendimiento:** La auth por parámetro de consulta requiere un limitador de\n frecuencia basado en IP (búsqueda Redis por petición), lo que añade latencia.\n La auth por cabecera omite esto.\n- **Prevención de abuso:** Una URL `?key=` filtrada podría compartirse y sufrir\n bombardeo. El límite por IP contiene el radio de impacto.\n\n## Patrones 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### Herramientas basadas en navegador\n\nSi su herramienta solo puede 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\nLos servidores MCP siempre usan auth por cabecera vía la variable de entorno\n`SYNAPSE_MIND_KEY` — no se aplica ningún límite.\n\n### Importaciones en lote\n\nPara operaciones masivas (p. ej. importar 1000 memorias), use siempre auth por\ncabecera. Las importaciones en lote vía `?key=` alcanzarán el límite en menos\nde 1 minuto.\n\n## Cuotas (a nivel de mind)\n\nActualmente no existen cuotas por mind en cuanto a tamaño de almacenamiento o\ncantidad de memorias. Todos los límites son a nivel de auth/IP, no a nivel de\ndatos. Esto podría cambiar en el futuro para equidad multi-tenant.\n\n## Monitoreo de su 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 pasos\n\n- [Autenticación](/docs/getting-started/authentication)\n- [Errores y manejo de errores](/docs/api/errors)\n","content_html":"

Límites de frecuencia y cuotas

\n

Synapse tiene una política de límites de frecuencia simple y predecible,\ndiseñada para prevenir el abuso sin estorbar el uso legítimo.

\n

Política de límites de frecuencia

\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 authLímiteÁmbito
Mind Key (Authorization: Bearer)NingunoPor mind
Mind Key (?key=)60 req/minPor IP
JWT (Authorization: Bearer)NingunoPor usuario
Endpoints públicosNingunoGlobal
\n
**Use siempre la cabecera `Authorization: Bearer`** cuando sea posible. No\ntiene límite de frecuencia. Use `?key=` solo para herramientas que no puedan\nestablecer cabeceras personalizadas.

Cabeceras de límite de frecuencia

\n

Cuando use auth con ?key=, las respuestas incluyen cabeceras de límite:

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

Cuando supere el límite:

\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}

Cuando alcanza un límite de frecuencia

\n

Si obtiene un 429:

\n
    \n

  1. Cambie a la cabecera 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. O espere Retry-After segundos y reintente.

    \n
    3. \n
\n

Por qué existe el límite de ?key=

\n

El parámetro de consulta ?key= es conveniente para herramientas que solo usan\nURLs (navegadores, comandos open), pero tiene implicaciones de seguridad y\nrendimiento:

\n\n

Patrones recomendados

\n

Agentes LLM

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

Herramientas basadas en navegador

\n

Si su herramienta solo puede 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

Los servidores MCP siempre usan auth por cabecera vía la variable de entorno\nSYNAPSE_MIND_KEY — no se aplica ningún límite.

\n

Importaciones en lote

\n

Para operaciones masivas (p. ej. importar 1000 memorias), use siempre auth por\ncabecera. Las importaciones en lote vía ?key= alcanzarán el límite en menos\nde 1 minuto.

\n

Cuotas (a nivel de mind)

\n

Actualmente no existen cuotas por mind en cuanto a tamaño de almacenamiento o\ncantidad de memorias. Todos los límites son a nivel de auth/IP, no a nivel de\ndatos. Esto podría cambiar en el futuro para equidad multi-tenant.

\n

Monitoreo de su 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 pasos

\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"]}