{"title":"Limiti di traffico e quote","slug":"rate-limits","category":"api","summary":"Politica di rate limit dell'API Synapse — header Bearer (illimitato), ?key= (60/min), endpoint pubblici.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":353,"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":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Limiti di traffico e quote\n\nSynapse ha una politica di rate limit semplice e prevedibile, progettata per\nprevenire abusi senza intralciare l'uso legittimo.\n\n## Politica di rate limit\n\n| Metodo di auth | Limite | Ambito |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **Nessuno** | Per-mente |\n| Mind Key (`?key=`) | 60 req/min | Per-IP |\n| JWT (`Authorization: Bearer`) | **Nessuno** | Per-utente |\n| Endpoint pubblici | **Nessuno** | Globale |\n\n> [!TIP]\n> **Usi sempre l'header `Authorization: Bearer`** quando possibile. Non ha\n> limiti di traffico. Usi `?key=` solo per strumenti che non possono impostare\n> header personalizzati.\n\n## Header di rate limit\n\nQuando usa l'autenticazione `?key=`, le risposte includono header di rate limit:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nQuando supera il limite:\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## Quando raggiunge un limite\n\nSe ottiene un 429:\n\n1. **Passi all'header Authorization** (consigliato):\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. **Oppure attenda `Retry-After` secondi** e riprovi.\n\n## Perché esiste il limite ?key=\n\nIl parametro query `?key=` è comodo per strumenti solo-URL (browser, comandi\n`open`), ma ha implicazioni di sicurezza e prestazioni:\n\n- **Sicurezza:** I parametri query vengono registrati nei log di accesso del\n server, nella cronologia del browser e negli header Referer. Limitarne l'uso\n riduce l'esposizione.\n- **Prestazioni:** L'autenticazione tramite parametro query richiede un rate\n limiter basato su IP (lookup Redis per richiesta), che aggiunge latenza.\n L'autenticazione tramite header lo salta.\n- **Prevenzione abusi:** Un URL `?key=` leakato potrebbe essere condiviso e\n bombardato di richieste. Il limite per IP contiene il raggio d'azione.\n\n## Modelli consigliati\n\n### Agenti 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### Strumenti basati su browser\n\nSe il suo strumento può solo aprire URL:\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### Server MCP\n\nI server MCP usano sempre l'autenticazione tramite header usando la variabile\ndi ambiente `SYNAPSE_MIND_KEY` — nessun limite di traffico si applica.\n\n### Importazioni bulk\n\nPer operazioni bulk (es. importare 1000 memorie), usi sempre l'autenticazione\ntramite header. Le importazioni bulk tramite `?key=` raggiungono il limite entro\n1 minuto.\n\n## Quote (livello mente)\n\nAttualmente non ci sono quote per mente sulla dimensione di archiviazione o\nsul numero di memorie. Tutti i limiti sono a livello di auth/IP, non di dati.\nQuesto potrebbe cambiare in futuro per equità multi-tenant.\n\n## Monitoraggio dell'utilizzo\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## Prossimi passi\n\n- [Autenticazione](/docs/getting-started/authentication)\n- [Errori e gestione degli errori](/docs/api/errors)\n","content_html":"

Limiti di traffico e quote

\n

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

\n

Politica di rate limit

\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
Metodo di authLimiteAmbito
Mind Key (Authorization: Bearer)NessunoPer-mente
Mind Key (?key=)60 req/minPer-IP
JWT (Authorization: Bearer)NessunoPer-utente
Endpoint pubbliciNessunoGlobale
\n
**Usi sempre l'header `Authorization: Bearer`** quando possibile. Non ha\nlimiti di traffico. Usi `?key=` solo per strumenti che non possono impostare\nheader personalizzati.

Header di rate limit

\n

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

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

Quando supera il limite:

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

Quando raggiunge un limite

\n

Se ottiene un 429:

\n
    \n

  1. Passi all'header Authorization (consigliato):

    \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. Oppure attenda Retry-After secondi e riprovi.

    \n
    3. \n
\n

Perché esiste il limite ?key=

\n

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

\n\n

Modelli consigliati

\n

Agenti LLM

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

Strumenti basati su browser

\n

Se il suo strumento può solo aprire URL:

\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

Server MCP

\n

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

\n

Importazioni bulk

\n

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

\n

Quote (livello mente)

\n

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

\n

Monitoraggio dell'utilizzo

\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

Prossimi passi

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