# Rate Limits & Quotas

Synapse มีนโยบาย rate limit ที่เรียบง่ายและคาดเดาได้ ออกแบบเพื่อป้องกันการใช้งานในทางที่ผิดโดยไม่ขัดขวางการใช้งานที่ชอบด้วย

## นโยบาย Rate Limit

| วิธี Auth | Limit | Scope |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **None** | Per-mind |
| Mind Key (`?key=`) | 60 req/min | Per-IP |
| JWT (`Authorization: Bearer`) | **None** | Per-user |
| Public endpoints | **None** | Global |

> [!TIP]
> **ใช้ `Authorization: Bearer` header เสมอเมื่อทำได้** ไม่มี rate limit ใช้ `?key=` เฉพาะเครื่องมือที่ตั้ง custom header ไม่ได้

## Rate Limit Headers

เมื่อคุณใช้ auth ผ่าน `?key=` response จะมี rate limit headers:

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

เมื่อคุณเกิน limit:

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

## เมื่อคุณกระทบ Rate Limit

หากคุณได้ 429:

1. **เปลี่ยนไปใช้ Authorization header** (แนะนำ):
   ```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` วินาที** แล้ว retry

## ทำไมถึงมี Limit ของ ?key=

`?key=` query parameter สะดวกสำหรับเครื่องมือ URL-only (browser, คำสั่ง `open`) แต่มีผลกระทบด้านความปลอดภัยและประสิทธิภาพ:

- **ความปลอดภัย:** query parameter ถูกบันทึกใน server access log, browser history และ Referer header การจำกัดการใช้งานช่วยลดการสัมผัส
- **ประสิทธิภาพ:** auth ผ่าน query parameter ต้องการ rate limiter ที่ใช้ IP (Redis lookup ต่อ request) ซึ่งเพิ่ม latency auth ผ่าน header ข้ามสิ่งนี้ไป
- **การป้องกันการใช้งานในทางที่ผิด:** URL `?key=` ที่รั่วไหลอาจถูกแชร์และถูก hammer limit ต่อ IP จำกัดผลกระทบ

## รูปแบบที่แนะนำ

### LLM agent

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

### เครื่องมือแบบ Browser

หากเครื่องมือของคุณเปิด 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 server

MCP server ใช้ header auth เสมอผ่าน env var `SYNAPSE_MIND_KEY` — ไม่มี rate limit

### การนำเข้าแบบ bulk

สำหรับการดำเนินการแบบ bulk (เช่น นำเข้า memory 1000 รายการ) ให้ใช้ header auth เสมอ การนำเข้าแบบ bulk ผ่าน `?key=` จะกระทบ rate limit ภายใน 1 นาที

## Quotas (ระดับ Mind)

ปัจจุบันไม่มี quota ต่อ mind สำหรับขนาด storage หรือจำนวน memory limit ทั้งหมดอยู่ในระดับ auth/IP ไม่ใช่ในระดับข้อมูล อาจเปลี่ยนแปลงในอนาคตเพื่อความเป็นธรรมใน multi-tenant

## การตรวจสอบการใช้งานของคุณ

```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)