Rate Limits & Quotas

Synapse has a simple, predictable rate limit policy designed to prevent abuse while not getting in the way of legitimate usage.

Rate Limit Policy

Rate Limit Headers

When you use ?key= auth, responses include rate limit headers:

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

When you exceed the limit:

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."
}

When You Hit a Rate Limit

If you get a 429:

1. Switch to Authorization header (recommended):

   # 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. Or wait Retry-After seconds and retry.

Why the ?key= Limit Exists

The ?key= query parameter is convenient for URL-only tools (browsers, open commands), but it is deprecated and gated server-side by AUTH_QUERY_KEY_MODE (deny by default; allow re-enables query-param auth). It has security and performance implications:

• Security: Query parameters are logged in server access logs, browser history, and Referer headers. Limiting usage reduces exposure.
• Performance: Query-parameter auth requires an IP-based rate limiter (Redis lookup per request), which adds latency. Header auth skips this.
• Abuse prevention: A leaked ?key= URL could be shared and hammered. The IP limit contains the blast radius.

Recommended Patterns

LLM agents

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

Browser-based tools

If your tool can only open URLs:

# Legacy fallback (deprecated, 60/min per IP, gated by AUTH_QUERY_KEY_MODE).
# Never share or bookmark such URLs — the key lands in logs and history.
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Preferred: switch to a tool that supports headers
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP server

MCP servers always use header auth via SYNAPSE_MIND_KEY env var — no rate limit applies.

Bulk imports

For bulk operations (e.g. importing 1000 memories), always use header auth. Bulk imports via ?key= will hit the rate limit within 1 minute.

Quotas (Mind-Level)

There are currently no per-mind quotas on storage size or memory count. All limits are at the auth/IP level, not the data level. This may change in the future for multi-tenant fairness.

Monitoring Your Usage

# 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

Next Steps

• Authentication
• Errors & Error Handling