Rate Limits & Quotas

Synapse はシンプルで予測可能なレート制限ポリシーを採用しており、悪用を防ぎつつ正当な利用を妨げません。

レート制限ポリシー

レート制限ヘッダー

?key= 認証を使用する場合、レスポンスにレート制限ヘッダーが含まれます。

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

制限を超過した場合：

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

レート制限に達した場合

429 を受け取った場合：

1. Authorization ヘッダーに切り替える（推奨）：

   # 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. または Retry-After 秒待機してから再試行してください。

?key= 制限が存在する理由

?key= クエリパラメータは URL 単体のツール（ブラウザ、open コマンド）に便利ですが、セキュリティとパフォーマンスの懸念があります。

• セキュリティ： クエリパラメータはサーバーのアクセスログ、ブラウザ履歴、Referer ヘッダーに記録されます。利用を制限することで露出を減らせます。
• パフォーマンス： クエリパラメータ認証は IP ベースのレートリミッタを必要とし（リクエストごとに Redis ルックアップ）、レイテンシが増加します。ヘッダー認証はこれをスキップします。
• 悪用防止： 流出した ?key= URL は共有され大量リクエストを受ける可能性があります。IP 制限は被害範囲を限定します。

推奨パターン

LLM エージェント

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

ブラウザベースのツール

ツールが 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

MCP サーバー

MCP サーバーは常に SYNAPSE_MIND_KEY 環境変数経由でヘッダー認証を使用します — レート制限は適用されません。

一括インポート

一括操作（例：1000 件のメモリインポート）では、常にヘッダー認証を使用してください。?key= 経由の一括インポートは 1 分以内にレート制限に達します。

クォータ（mind レベル）

現在、ストレージサイズやメモリ数に関する mind ごとのクォータはありません。すべての制限はデータレベルではなく、認証/IP レベルです。マルチテナントの公平性のため、将来的に変更される可能性があります。

利用状況の監視

# 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

次のステップ

• Authentication
• Errors & Error Handling