Límites de frecuencia y cuotas

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

Política de límites de frecuencia

Cabeceras de límite de frecuencia

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

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

Cuando supere el límite:

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."
}

Cuando alcanza un límite de frecuencia

Si obtiene un 429:

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

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

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

• Seguridad: Los parámetros de consulta se registran en logs de acceso del servidor, historial del navegador y cabeceras Referer. Limitar su uso reduce la exposición.
• Rendimiento: La auth por parámetro de consulta requiere un limitador de frecuencia basado en IP (búsqueda Redis por petición), lo que añade latencia. La auth por cabecera omite esto.
• Prevención de abuso: Una URL ?key= filtrada podría compartirse y sufrir bombardeo. El límite por IP contiene el radio de impacto.

Patrones recomendados

Agentes LLM

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

Herramientas basadas en navegador

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

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

Importaciones en lote

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

Cuotas (a nivel de mind)

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

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

• Autenticación
• Errores y manejo de errores