{"title":"Giới hạn tốc độ & Hạn ngạch","slug":"rate-limits","category":"api","summary":"Chính sách giới hạn tốc độ cho Synapse API — Bearer header (không giới hạn), ?key= (60/phút), endpoint công khai.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":459,"read_minutes":2,"llm_context":"Mind Key (Authorization: Bearer header) → NO rate limit\nMind Key (?key= query param) → 60 req/min per IP\nJWT (Authorization: Bearer header) → NO rate limit\nPublic endpoints (/tools/*, /docs, /health, /endpoints) → NO rate limit\nRate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After\nRecommendation: ALWAYS use Authorization header. Use ?key= only for URL-only tools.\n","lang":"vi","translated":true,"requested_lang":"vi","content_markdown":"\n# Giới hạn tốc độ & Hạn ngạch\n\nSynapse có chính sách giới hạn tốc độ đơn giản, dự đoán được, được thiết kế để\nngăn lạm dụng mà không cản trở sử dụng hợp pháp.\n\n## Chính sách giới hạn tốc độ\n\n| Phương thức xác thực | Giới hạn | Phạm vi |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **Không** | Mỗi mind |\n| Mind Key (`?key=`) | 60 yêu cầu/phút | Mỗi IP |\n| JWT (`Authorization: Bearer`) | **Không** | Mỗi người dùng |\n| Endpoint công khai | **Không** | Toàn cầu |\n\n> [!TIP]\n> **Luôn sử dụng header `Authorization: Bearer`** khi có thể. Nó không có\n> 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.\n\n## Header giới hạn tốc độ\n\nKhi bạn dùng xác thực `?key=`, phản hồi bao gồm header giới hạn tốc độ:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\nKhi bạn vượt giới hạn:\n\n```\nHTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n \"statusCode\": 429,\n \"error\": \"Too Many Requests\",\n \"message\": \"Rate limit exceeded. Use Authorization header for unlimited access.\"\n}\n```\n\n## Khi bạn gặp giới hạn tốc độ\n\nNếu bạn nhận 429:\n\n1. **Chuyển sang Authorization header** (khuyến nghị):\n ```bash\n # Don't: ?key=YOUR_MIND_KEY (60/min limit)\n curl \".../memory/recall?key=YOUR_MIND_KEY\"\n \n # Do: Authorization header (unlimited)\n curl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n ```\n\n2. **Hoặc đợi `Retry-After` giây** và thử lại.\n\n## Tại sao giới hạn ?key= tồn tại\n\nTham số query `?key=` tiện lợi cho các công cụ chỉ dùng URL (trình duyệt, lệnh\n`open`), nhưng có ý nghĩa bảo mật và hiệu suất:\n\n- **Bảo mật:** Tham số query được ghi trong nhật ký truy cập server, lịch sử\n trình duyệt, và header Referer. Giới hạn sử dụng làm giảm rủi ro lộ lọt.\n- **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\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\n bỏ qua bước này.\n- **Ngăn lạm dụng:** Một URL `?key=` bị lộ có thể được chia sẻ và truy cập dồn\n dập. Giới hạn IP giới hạn thiệt hại.\n\n## Mẫu khuyến nghị\n\n### LLM agent\n\n```python\n# Always use header auth\nheaders = {\"Authorization\": f\"Bearer {MIND_KEY}\"}\nresponse = requests.get(f\"{URL}/memory/recall\", headers=headers)\n```\n\n### Công cụ dựa trên trình duyệt\n\nNếu công cụ của bạn chỉ có thể mở URL:\n\n```bash\n# OK for occasional use (under 60/min)\nopen \"https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY\"\n\n# For frequent use, switch to a tool that supports headers\ncurl -H \"Authorization: Bearer YOUR_MIND_KEY\" .../memory/recall\n```\n\n### MCP server\n\nMCP server luôn sử dụng xác thực header qua biến môi trường `SYNAPSE_MIND_KEY`\n— không áp dụng giới hạn tốc độ.\n\n### Nhập hàng loạt\n\nĐố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\nheader. Nhập hàng loạt qua `?key=` sẽ gặp giới hạn tốc độ trong vòng 1 phút.\n\n## Hạn ngạch (cấp Mind)\n\nHiệ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ớ.\nTấ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ể\nthay đổi trong tương lai để đảm bảo công bằng multi-tenant.\n\n## Giám sát sử dụng\n\n```bash\n# Check your current rate limit status (with ?key= auth)\ncurl -i \"https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY\" | grep -i ratelimit\n\n# Output:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840\n```\n\n## Bước tiếp theo\n\n- [Xác thực](/docs/getting-started/authentication)\n- [Lỗi & Xử lý lỗi](/docs/api/errors)\n","content_html":"

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

\n

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

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Phương thức xác thựcGiới hạnPhạm vi
Mind Key (Authorization: Bearer)KhôngMỗi mind
Mind Key (?key=)60 yêu cầu/phútMỗi IP
JWT (Authorization: Bearer)KhôngMỗi người dùng
Endpoint công khaiKhôngToàn cầu
\n
**Luôn sử dụng header `Authorization: Bearer`** khi có thể. Nó không có\ngiớ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 độ

\n

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

\n
X-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840

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

\n
HTTP/1.1 429 Too Many Requests\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 0\nRetry-After: 42\nContent-Type: application/json\n\n{\n  "statusCode": 429,\n  "error": "Too Many Requests",\n  "message": "Rate limit exceeded. Use Authorization header for unlimited access."\n}

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

\n

Nếu bạn nhận 429:

\n
    \n

  1. Chuyển sang Authorization header (khuyến nghị):

    \n
    # Don't: ?key=YOUR_MIND_KEY (60/min limit)\ncurl ".../memory/recall?key=YOUR_MIND_KEY"\n\n# Do: Authorization header (unlimited)\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall
    2. \n

  2. Hoặc đợi Retry-After giây và thử lại.

    \n
    3. \n
\n

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

\n

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

\n\n

Mẫu khuyến nghị

\n

LLM agent

\n
# Always use header auth\nheaders = {"Authorization": f"Bearer {MIND_KEY}"}\nresponse = requests.get(f"{URL}/memory/recall", headers=headers)

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

\n

Nếu công cụ của bạn chỉ có thể mở URL:

\n
# OK for occasional use (under 60/min)\nopen "https://synapse.schaefer.zone/memory/recall?key=YOUR_MIND_KEY"\n\n# For frequent use, switch to a tool that supports headers\ncurl -H "Authorization: Bearer YOUR_MIND_KEY" .../memory/recall

MCP server

\n

MCP server luôn sử dụng xác thực header qua biến môi trường SYNAPSE_MIND_KEY\n— không áp dụng giới hạn tốc độ.

\n

Nhập hàng loạt

\n

Đố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\nheader. Nhập hàng loạt qua ?key= sẽ gặp giới hạn tốc độ trong vòng 1 phút.

\n

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

\n

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ớ.\nTấ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ể\nthay đổi trong tương lai để đảm bảo công bằng multi-tenant.

\n

Giám sát sử dụng

\n
# Check your current rate limit status (with ?key= auth)\ncurl -i "https://synapse.schaefer.zone/memory/stats?key=YOUR_MIND_KEY" | grep -i ratelimit\n\n# Output:\n# X-RateLimit-Limit: 60\n# X-RateLimit-Remaining: 58\n# X-RateLimit-Reset: 1782567840

Bước tiếp theo

\n\n","urls":{"html":"/docs/api/rate-limits","text":"/docs/api/rate-limits?format=text","json":"/docs/api/rate-limits?format=json","llm":"/docs/api/rate-limits?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}