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

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):

   # 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

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

# 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

# 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
• Errori e gestione degli errori