# 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

| Método de auth | Límite | Ámbito |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Ninguno** | Por mind |
| Mind Key (`?key=`) | 60 req/min | Por IP |
| JWT (`Authorization: Bearer`) | **Ninguno** | Por usuario |
| Endpoints públicos | **Ninguno** | Global |

> [!TIP]
> **Use siempre la cabecera `Authorization: Bearer`** cuando sea posible. No
> tiene límite de frecuencia. Use `?key=` solo para herramientas que no puedan
> establecer cabeceras personalizadas.

## 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):
   ```bash
   # 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

```python
# 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:

```bash
# 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

```bash
# 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](/docs/getting-started/authentication)
- [Errores y manejo de errores](/docs/api/errors)