Rate Limits & Kontingente

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

Rate-Limit-Richtlinie

Rate-Limit-Header

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

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

Wenn du das Limit überschreitest:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42
Content-Type: application/json

{
  "error": "rate_limited",
  "message": "Too many requests with query-param auth. Slow down or use Authorization header."
}

Wenn du ein Rate Limit triffst

Bei einer 429:

1. Wechsle zum Authorization-Header (empfohlen):

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

Warum das ?key=-Limit existiert

Der ?key=-Query-Parameter ist praktisch für reine URL-Tools (Browser, open-Befehle), ist aber veraltet und wird serverseitig über AUTH_QUERY_KEY_MODE gesteuert (deny als Default; allow reaktiviert die Query-Param-Auth). Er hat Sicherheits- und Performance-Auswirkungen:

• Sicherheit: Query-Parameter werden in Server-Access-Logs, Browser-Verlauf und Referer-Headern protokolliert. Eine Begrenzung reduziert die Exposition.
• Performance: Query-Parameter-Auth erfordert einen IP-basierten Rate-Limiter (Redis-Lookup pro Anfrage), was Latenz erzeugt. Header-Auth umgeht das.
• Missbrauchsvermeidung: Eine geleakte ?key=-URL könnte geteilt und abgefeuert werden. Das IP-Limit begrenzt den Schadensradius.

Empfohlene Patterns

LLM-Agenten

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

Browserbasierte Tools

Wenn dein Tool nur URLs öffnen kann:

# Veralteter Rückfall (deprecated, 60/min pro IP, gesteuert über
# AUTH_QUERY_KEY_MODE). Solche URLs niemals teilen oder als Lesezeichen
# speichern — der Key landet in Logs und Verlauf.
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Empfohlen: auf ein Tool mit Header-Unterstützung wechseln
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP-Server

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

Bulk-Importe

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

Kontingente (Mind-Ebene)

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

Eigene Nutzung beobachten

# Rate limit headers are attached to ?key= responses (legacy path):
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

Nächste Schritte

• Authentifizierung
• Errors & Fehlerbehandlung