# Rate Limits & Quotas

Synapse memiliki kebijakan rate limit yang sederhana dan dapat diprediksi,
dirancang untuk mencegah penyalahgunaan tanpa menghambat penggunaan yang sah.

## Kebijakan Rate Limit

| Metode Auth | Batas | Cakupan |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Tidak ada** | Per-mind |
| Mind Key (`?key=`) | 60 req/menit | Per-IP |
| JWT (`Authorization: Bearer`) | **Tidak ada** | Per-user |
| Endpoint publik | **Tidak ada** | Global |

> [!TIP]
> **Selalu gunakan header `Authorization: Bearer`** bila memungkinkan. Header ini
> tidak memiliki rate limit. Gunakan `?key=` hanya untuk alat yang tidak dapat
> mengatur header khusus.

## Header Rate Limit

Saat Anda menggunakan autentikasi `?key=`, respons menyertakan header rate limit:

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

Saat Anda melebihi batas:

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

## Saat Anda Mengenai Rate Limit

Jika Anda mendapat 429:

1. **Beralih ke header Authorization** (disarankan):
   ```bash
   # Jangan: ?key=YOUR_MIND_KEY (batas 60/menit)
   curl ".../memory/recall?key=YOUR_MIND_KEY"
   
   # Lakukan: header Authorization (tidak terbatas)
   curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
   ```

2. **Atau tunggu `Retry-After` detik** lalu coba lagi.

## Mengapa Batas ?key= Ada

Parameter query `?key=` nyaman untuk alat yang hanya menggunakan URL (browser,
perintah `open`), tetapi memiliki implikasi keamanan dan performa:

- **Keamanan:** Parameter query dicatat dalam log akses server, riwayat
  browser, dan header Referer. Membatasi penggunaan mengurangi paparan.
- **Performa:** Autentikasi parameter query memerlukan rate limiter berbasis IP
  (pencarian Redis per permintaan), yang menambah latensi. Autentikasi header
  melewati ini.
- **Pencegahan penyalahgunaan:** URL `?key=` yang bocor dapat dibagikan dan
  dibombardir. Batas IP membatasi dampak.

## Pola yang Disarankan

### Agen LLM

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

### Alat berbasis browser

Jika alat Anda hanya dapat membuka URL:

```bash
# OK untuk penggunaan sesekali (di bawah 60/menit)
open "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"

# Untuk penggunaan sering, beralih ke alat yang mendukung header
curl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
```

### MCP server

MCP server selalu menggunakan autentikasi header melalui env var
`SYNAPSE_MIND_KEY` — tidak ada rate limit yang berlaku.

### Impor massal

Untuk operasi massal (mis. mengimpor 1000 memori), selalu gunakan autentikasi
header. Impor massal melalui `?key=` akan mengenai rate limit dalam 1 menit.

## Quota (Level Mind)

Saat ini tidak ada kuota per-mind untuk ukuran penyimpanan atau jumlah memori.
Semua batas ada di level auth/IP, bukan level data. Ini mungkin berubah di
masa depan untuk keadilan multi-tenant.

## Memantau Penggunaan Anda

```bash
# Periksa status rate limit Anda saat ini (dengan autentikasi ?key=)
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
```

## Langkah Berikutnya

- [Autentikasi](/docs/getting-started/authentication)
- [Errors & Error Handling](/docs/api/errors)