# Giới hạn tốc độ & Hạn ngạch

Synapse có chính sách giới hạn tốc độ đơn giản, dự đoán được, được thiết kế để
ngăn lạm dụng mà không cản trở sử dụng hợp pháp.

## Chính sách giới hạn tốc độ

| Phương thức xác thực | Giới hạn | Phạm vi |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **Không** | Mỗi mind |
| Mind Key (`?key=`) | 60 yêu cầu/phút | Mỗi IP |
| JWT (`Authorization: Bearer`) | **Không** | Mỗi người dùng |
| Endpoint công khai | **Không** | Toàn cầu |

> [!TIP]
> **Luôn sử dụng header `Authorization: Bearer`** khi có thể. Nó không có
> giới hạn tốc độ. Chỉ dùng `?key=` cho các công cụ không thể đặt header tùy chỉnh.

## Header giới hạn tốc độ

Khi bạn dùng xác thực `?key=`, phản hồi bao gồm header giới hạn tốc độ:

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

Khi bạn vượt giới hạn:

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

## Khi bạn gặp giới hạn tốc độ

Nếu bạn nhận 429:

1. **Chuyển sang Authorization header** (khuyến nghị):
   ```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. **Hoặc đợi `Retry-After` giây** và thử lại.

## Tại sao giới hạn ?key= tồn tại

Tham số query `?key=` tiện lợi cho các công cụ chỉ dùng URL (trình duyệt, lệnh
`open`), nhưng có ý nghĩa bảo mật và hiệu suất:

- **Bảo mật:** Tham số query được ghi trong nhật ký truy cập server, lịch sử
  trình duyệt, và header Referer. Giới hạn sử dụng làm giảm rủi ro lộ lọt.
- **Hiệu suất:** Xác thực qua tham số query yêu cầu bộ giới hạn tốc độ dựa trên
  IP (tra cứu Redis mỗi yêu cầu), điều này làm tăng độ trễ. Xác thực header
  bỏ qua bước này.
- **Ngăn lạm dụng:** Một URL `?key=` bị lộ có thể được chia sẻ và truy cập dồn
  dập. Giới hạn IP giới hạn thiệt hại.

## Mẫu khuyến nghị

### LLM agent

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

### Công cụ dựa trên trình duyệt

Nếu công cụ của bạn chỉ có thể mở 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 luôn sử dụng xác thực header qua biến môi trường `SYNAPSE_MIND_KEY`
— không áp dụng giới hạn tốc độ.

### Nhập hàng loạt

Đối với thao tác hàng loạt (ví dụ nhập 1000 bộ nhớ), luôn sử dụng xác thực
header. Nhập hàng loạt qua `?key=` sẽ gặp giới hạn tốc độ trong vòng 1 phút.

## Hạn ngạch (cấp Mind)

Hiện tại không có hạn ngạch mỗi mind về kích thước lưu trữ hoặc số lượng bộ nhớ.
Tất cả giới hạn đều ở cấp xác thực/IP, không phải cấp dữ liệu. Điều này có thể
thay đổi trong tương lai để đảm bảo công bằng multi-tenant.

## Giám sát sử dụng

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

## Bước tiếp theo

- [Xác thực](/docs/getting-started/authentication)
- [Lỗi & Xử lý lỗi](/docs/api/errors)