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 độ

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ị):

   # 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

# 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:

# 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

# 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
• Lỗi & Xử lý lỗi