# Rate Limits & Quotas

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

## レート制限ポリシー

| 認証方法 | 制限 | スコープ |
|-------------|-------|-------|
| Mind Key（`Authorization: Bearer`） | **なし** | mind ごと |
| Mind Key（`?key=`） | 60 回/分 | IP ごと |
| JWT（`Authorization: Bearer`） | **なし** | ユーザーごと |
| パブリックエンドポイント | **なし** | グローバル |

> [!TIP]
> **可能な限り常に `Authorization: Bearer` ヘッダーを使用してください。** レート制限がありません。`?key=` はカスタムヘッダーを設定できないツールでのみ使用してください。

## レート制限ヘッダー

`?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 ヘッダーに切り替える**（推奨）：
   ```bash
   # 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 エージェント

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

### ブラウザベースのツール

ツールが URL を開くことしかできない場合：

```bash
# 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 レベルです。マルチテナントの公平性のため、将来的に変更される可能性があります。

## 利用状況の監視

```bash
# 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](/docs/getting-started/authentication)
- [Errors & Error Handling](/docs/api/errors)