{"title":"Rate Limits & Kontingente","slug":"rate-limits","category":"api","summary":"Rate-Limit-Richtlinien für die Synapse-API — Bearer-Header (unbegrenzt), ?key= (60/min), öffentliche Endpunkte.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":281,"read_minutes":1,"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":"de","translated":true,"requested_lang":"de","content_markdown":"\n# Rate Limits & Kontingente\n\nSynapse hat eine einfache, vorhersehbare Rate-Limit-Richtlinie, die Missbrauch\nverhindern soll, ohne legitime Nutzung auszubremsen.\n\n## Rate-Limit-Richtlinie\n\n| Auth-Methode | Limit | Scope |\n|---------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **Keins** | Pro-Mind |\n| Mind Key (`?key=`) | 60 req/min | Pro-IP |\n| JWT (`Authorization: Bearer`) | **Keins** | Pro-Nutzer |\n| Öffentliche Endpunkte | **Keins** | Global |\n\n> [!TIP]\n> **Verwende immer den `Authorization: Bearer`-Header**, wenn möglich. Er hat\n> kein Rate Limit. Nutze `?key=` nur für Tools, die keine eigenen Header setzen\n> können.\n\n## Rate-Limit-Header\n\nWenn du `?key=`-Auth nutzt, enthalten Antworten Rate-Limit-Header:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nWenn du das Limit überschreitest:\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## Wenn du ein Rate Limit triffst\n\nBei einer 429:\n\n1. **Wechsle zum Authorization-Header** (empfohlen):\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. **Oder warte `Retry-After` Sekunden** und versuche es erneut.\n\n## Warum das ?key=-Limit existiert\n\nDer `?key=`-Query-Parameter ist praktisch für reine URL-Tools (Browser,\n`open`-Befehle), hat aber Sicherheits- und Performance-Auswirkungen:\n\n- **Sicherheit:** Query-Parameter werden in Server-Access-Logs, Browser-Verlauf\n und Referer-Headern protokolliert. Eine Begrenzung reduziert die Exposition.\n- **Performance:** Query-Parameter-Auth erfordert einen IP-basierten Rate-Limiter\n (Redis-Lookup pro Anfrage), was Latenz erzeugt. Header-Auth umgeht das.\n- **Missbrauchsvermeidung:** Eine geleakte `?key=`-URL könnte geteilt und\n abgefeuert werden. Das IP-Limit begrenzt den Schadensradius.\n\n## Empfohlene Patterns\n\n### LLM-Agenten\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### Browserbasierte Tools\n\nWenn dein Tool nur URLs öffnen kann:\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### MCP-Server\n\nMCP-Server verwenden immer Header-Auth via `SYNAPSE_MIND_KEY`-Env-Var — kein\nRate Limit greift.\n\n### Bulk-Importe\n\nFür Bulk-Operationen (z. B. 1000 Memories importieren) verwende immer Header-Auth.\nBulk-Importe via `?key=` erreichen das Limit innerhalb einer Minute.\n\n## Kontingente (Mind-Ebene)\n\nAktuell gibt es keine Mind-spezifischen Kontingente für Speichergröße oder\nMemory-Anzahl. Alle Limits sind auf Auth/IP-Ebene, nicht auf Datenebene. Das\nkann sich in Zukunft für Multi-Tenant-Fairness ändern.\n\n## Eigene Nutzung beobachten\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## Nächste Schritte\n\n- [Authentifizierung](/docs/getting-started/authentication)\n- [Errors & Fehlerbehandlung](/docs/api/errors)\n","content_html":"

Rate Limits & Kontingente

\n

Synapse hat eine einfache, vorhersehbare Rate-Limit-Richtlinie, die Missbrauch\nverhindern soll, ohne legitime Nutzung auszubremsen.

\n

Rate-Limit-Richtlinie

\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
Auth-MethodeLimitScope
Mind Key (Authorization: Bearer)KeinsPro-Mind
Mind Key (?key=)60 req/minPro-IP
JWT (Authorization: Bearer)KeinsPro-Nutzer
Öffentliche EndpunkteKeinsGlobal
\n
**Verwende immer den `Authorization: Bearer`-Header**, wenn möglich. Er hat\nkein Rate Limit. Nutze `?key=` nur für Tools, die keine eigenen Header setzen\nkönnen.

Rate-Limit-Header

\n

Wenn du ?key=-Auth nutzt, enthalten Antworten Rate-Limit-Header:

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

Wenn du das Limit überschreitest:

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

Wenn du ein Rate Limit triffst

\n

Bei einer 429:

\n
    \n

  1. Wechsle zum Authorization-Header (empfohlen):

    \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. Oder warte Retry-After Sekunden und versuche es erneut.

    \n
    3. \n
\n

Warum das ?key=-Limit existiert

\n

Der ?key=-Query-Parameter ist praktisch für reine URL-Tools (Browser,\nopen-Befehle), hat aber Sicherheits- und Performance-Auswirkungen:

\n\n

Empfohlene Patterns

\n

LLM-Agenten

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

Browserbasierte Tools

\n

Wenn dein Tool nur URLs öffnen kann:

\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

MCP-Server

\n

MCP-Server verwenden immer Header-Auth via SYNAPSE_MIND_KEY-Env-Var — kein\nRate Limit greift.

\n

Bulk-Importe

\n

Für Bulk-Operationen (z. B. 1000 Memories importieren) verwende immer Header-Auth.\nBulk-Importe via ?key= erreichen das Limit innerhalb einer Minute.

\n

Kontingente (Mind-Ebene)

\n

Aktuell gibt es keine Mind-spezifischen Kontingente für Speichergröße oder\nMemory-Anzahl. Alle Limits sind auf Auth/IP-Ebene, nicht auf Datenebene. Das\nkann sich in Zukunft für Multi-Tenant-Fairness ändern.

\n

Eigene Nutzung beobachten

\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ächste Schritte

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