{"title":"Rate Limits & Quotas","slug":"rate-limits","category":"api","summary":"Synapse API のレート制限ポリシー — Bearer ヘッダー（無制限）、?key=（60 回/分）、パブリックエンドポイント。","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":137,"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":"ja","translated":true,"requested_lang":"ja","content_markdown":"\n# Rate Limits & Quotas\n\nSynapse はシンプルで予測可能なレート制限ポリシーを採用しており、悪用を防ぎつつ正当な利用を妨げません。\n\n## レート制限ポリシー\n\n| 認証方法 | 制限 | スコープ |\n|-------------|-------|-------|\n| Mind Key（`Authorization: Bearer`） | **なし** | mind ごと |\n| Mind Key（`?key=`） | 60 回/分 | IP ごと |\n| JWT（`Authorization: Bearer`） | **なし** | ユーザーごと |\n| パブリックエンドポイント | **なし** | グローバル |\n\n> [!TIP]\n> **可能な限り常に `Authorization: Bearer` ヘッダーを使用してください。** レート制限がありません。`?key=` はカスタムヘッダーを設定できないツールでのみ使用してください。\n\n## レート制限ヘッダー\n\n`?key=` 認証を使用する場合、レスポンスにレート制限ヘッダーが含まれます。\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\n制限を超過した場合：\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## レート制限に達した場合\n\n429 を受け取った場合：\n\n1. **Authorization ヘッダーに切り替える**（推奨）：\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. **または `Retry-After` 秒待機**してから再試行してください。\n\n## ?key= 制限が存在する理由\n\n`?key=` クエリパラメータは URL 単体のツール（ブラウザ、`open` コマンド）に便利ですが、セキュリティとパフォーマンスの懸念があります。\n\n- **セキュリティ：** クエリパラメータはサーバーのアクセスログ、ブラウザ履歴、Referer ヘッダーに記録されます。利用を制限することで露出を減らせます。\n- **パフォーマンス：** クエリパラメータ認証は IP ベースのレートリミッタを必要とし（リクエストごとに Redis ルックアップ）、レイテンシが増加します。ヘッダー認証はこれをスキップします。\n- **悪用防止：** 流出した `?key=` URL は共有され大量リクエストを受ける可能性があります。IP 制限は被害範囲を限定します。\n\n## 推奨パターン\n\n### 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### ブラウザベースのツール\n\nツールが 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### MCP サーバー\n\nMCP サーバーは常に `SYNAPSE_MIND_KEY` 環境変数経由でヘッダー認証を使用します — レート制限は適用されません。\n\n### 一括インポート\n\n一括操作（例：1000 件のメモリインポート）では、常にヘッダー認証を使用してください。`?key=` 経由の一括インポートは 1 分以内にレート制限に達します。\n\n## クォータ（mind レベル）\n\n現在、ストレージサイズやメモリ数に関する mind ごとのクォータはありません。すべての制限はデータレベルではなく、認証/IP レベルです。マルチテナントの公平性のため、将来的に変更される可能性があります。\n\n## 利用状況の監視\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\n- [Authentication](/docs/getting-started/authentication)\n- [Errors & Error Handling](/docs/api/errors)\n","content_html":"

Rate Limits & Quotas

\n

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

\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\n
認証方法制限スコープ
Mind Key（Authorization: Bearer）なしmind ごと
Mind Key（?key=）60 回/分IP ごと
JWT（Authorization: Bearer）なしユーザーごと
パブリックエンドポイントなしグローバル
\n
**可能な限り常に `Authorization: Bearer` ヘッダーを使用してください。** レート制限がありません。`?key=` はカスタムヘッダーを設定できないツールでのみ使用してください。

レート制限ヘッダー

\n

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

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

制限を超過した場合：

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

レート制限に達した場合

\n

429 を受け取った場合：

\n
    \n

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

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

    \n
    3. \n
\n

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

\n

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

\n\n

推奨パターン

\n

LLM エージェント

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

ブラウザベースのツール

\n

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

MCP サーバー

\n

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

\n

一括インポート

\n

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

\n

クォータ（mind レベル）

\n

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

\n

利用状況の監視

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