# Limiti di traffico e quote

Synapse ha una politica di rate limit semplice e prevedibile, progettata per
prevenire abusi senza intralciare l'uso legittimo.

## Politica di rate limit

| Metodo di auth | Limite | Ambito |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Nessuno** | Per-mente |
| Mind Key (`?key=`) | 60 req/min | Per-IP |
| JWT (`Authorization: Bearer`) | **Nessuno** | Per-utente |
| Endpoint pubblici | **Nessuno** | Globale |

> [!TIP]
> **Usi sempre l'header `Authorization: Bearer`** quando possibile. Non ha
> limiti di traffico. Usi `?key=` solo per strumenti che non possono impostare
> header personalizzati.

## Header di rate limit

Quando usa l'autenticazione `?key=`, le risposte includono header di rate limit:

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

Quando supera il 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 raggiunge un limite

Se ottiene un 429:

1. **Passi all'header Authorization** (consigliato):
   ```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. **Oppure attenda `Retry-After` secondi** e riprovi.

## Perché esiste il limite ?key=

Il parametro query `?key=` è comodo per strumenti solo-URL (browser, comandi
`open`), ma ha implicazioni di sicurezza e prestazioni:

- **Sicurezza:** I parametri query vengono registrati nei log di accesso del
  server, nella cronologia del browser e negli header Referer. Limitarne l'uso
  riduce l'esposizione.
- **Prestazioni:** L'autenticazione tramite parametro query richiede un rate
  limiter basato su IP (lookup Redis per richiesta), che aggiunge latenza.
  L'autenticazione tramite header lo salta.
- **Prevenzione abusi:** Un URL `?key=` leakato potrebbe essere condiviso e
  bombardato di richieste. Il limite per IP contiene il raggio d'azione.

## Modelli consigliati

### Agenti LLM

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

### Strumenti basati su browser

Se il suo strumento può solo aprire URL:

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

### Server MCP

I server MCP usano sempre l'autenticazione tramite header usando la variabile
di ambiente `SYNAPSE_MIND_KEY` — nessun limite di traffico si applica.

### Importazioni bulk

Per operazioni bulk (es. importare 1000 memorie), usi sempre l'autenticazione
tramite header. Le importazioni bulk tramite `?key=` raggiungono il limite entro
1 minuto.

## Quote (livello mente)

Attualmente non ci sono quote per mente sulla dimensione di archiviazione o
sul numero di memorie. Tutti i limiti sono a livello di auth/IP, non di dati.
Questo potrebbe cambiare in futuro per equità multi-tenant.

## Monitoraggio dell'utilizzo

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

## Prossimi passi

- [Autenticazione](/docs/getting-started/authentication)
- [Errori e gestione degli errori](/docs/api/errors)