{"title":"속도 제한 및 할당량","slug":"rate-limits","category":"api","summary":"Synapse API의 속도 제한 정책 — Bearer 헤더 (무제한), ?key= (분당 60회), 공용 엔드포인트.","audience":["human","llm"],"tags":["api","rate-limits","quotas","throttling"],"difficulty":"beginner","updated":"2026-06-27","word_count":285,"read_minutes":1,"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":"ko","translated":true,"requested_lang":"ko","content_markdown":"\n# 속도 제한 및 할당량\n\nSynapse는 남용을 방지하면서 정상적인 사용을 방해하지 않는 단순하고\n예측 가능한 속도 제한 정책을 가지고 있습니다.\n\n## 속도 제한 정책\n\n| 인증 방법 | 제한 | 범위 |\n|-------------|-------|-------|\n| Mind Key (`Authorization: Bearer`) | **없음** | 마인드별 |\n| Mind Key (`?key=`) | 분당 60회 | IP별 |\n| JWT (`Authorization: Bearer`) | **없음** | 사용자별 |\n| 공용 엔드포인트 | **없음** | 전역 |\n\n> [!TIP]\n> **가능하면 항상 `Authorization: Bearer` 헤더를 사용하십시오.** 속도\n> 제한이 없습니다. `?key=`는 사용자 정의 헤더를 설정할 수 없는 도구에만\n> 사용하십시오.\n\n## 속도 제한 헤더\n\n`?key=` 인증을 사용할 때, 응답에는 속도 제한 헤더가 포함됩니다:\n\n```\nX-RateLimit-Limit: 60\nX-RateLimit-Remaining: 42\nX-RateLimit-Reset: 1782567840\n```\n\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## 속도 제한에 도달한 경우\n\n429를 받은 경우:\n\n1. **Authorization 헤더로 전환** (권장):\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. **또는 `Retry-After`초 대기** 후 재시도.\n\n## ?key= 제한이 존재하는 이유\n\n`?key=` 쿼리 파라미터는 URL 전용 도구(브라우저, `open` 명령어)에\n편리하지만, 보안 및 성능에 영향을 미칩니다:\n\n- **보안:** 쿼리 파라미터는 서버 접근 로그, 브라우저 기록, Referer 헤더에\n 기록됩니다. 사용량을 제한하면 노출이 줄어듭니다.\n- **성능:** 쿼리 파라미터 인증은 IP 기반 속도 제한기(요청당 Redis 조회)가\n 필요하여 지연이 추가됩니다. 헤더 인증은 이를 생략합니다.\n- **남용 방지:** 유출된 `?key=` URL은 공유되어 남용될 수 있습니다. IP\n 제한으로 피해 범위를 제한합니다.\n\n## 권장 패턴\n\n### LLM 에이전트\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### 브라우저 기반 도구\n\n도구가 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 서버\n\nMCP 서버는 항상 `SYNAPSE_MIND_KEY` 환경 변수를 통해 헤더 인증을\n사용합니다 — 속도 제한이 적용되지 않습니다.\n\n### 대량 가져오기\n\n대량 작업(예: 1000개 메모리 가져오기)의 경우, 항상 헤더 인증을\n사용하십시오. `?key=`를 통한 대량 가져오기는 1분 이내에 속도 제한에\n도달합니다.\n\n## 할당량 (마인드 수준)\n\n현재 저장소 크기나 메모리 수에 대한 마인드별 할당량이 없습니다. 모든\n제한은 데이터 수준이 아닌 인증/IP 수준에 있습니다. 이는 다중 테넌트\n공정성을 위해 향후 변경될 수 있습니다.\n\n## 사용량 모니터링\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## 다음 단계\n\n- [Authentication](/docs/getting-started/authentication)\n- [오류 및 오류 처리](/docs/api/errors)\n","content_html":"

속도 제한 및 할당량

\n

Synapse는 남용을 방지하면서 정상적인 사용을 방해하지 않는 단순하고\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\n\n
인증 방법제한범위
Mind Key (Authorization: Bearer)없음마인드별
Mind Key (?key=)분당 60회IP별
JWT (Authorization: Bearer)없음사용자별
공용 엔드포인트없음전역
\n
**가능하면 항상 `Authorization: Bearer` 헤더를 사용하십시오.** 속도\n제한이 없습니다. `?key=`는 사용자 정의 헤더를 설정할 수 없는 도구에만\n사용하십시오.

속도 제한 헤더

\n

?key= 인증을 사용할 때, 응답에는 속도 제한 헤더가 포함됩니다:

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

제한을 초과한 경우:

\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}

속도 제한에 도달한 경우

\n

429를 받은 경우:

\n
    \n

  1. Authorization 헤더로 전환 (권장):

    \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. 또는 Retry-After초 대기 후 재시도.

    \n
    3. \n
\n

?key= 제한이 존재하는 이유

\n

?key= 쿼리 파라미터는 URL 전용 도구(브라우저, open 명령어)에\n편리하지만, 보안 및 성능에 영향을 미칩니다:

\n\n

권장 패턴

\n

LLM 에이전트

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

브라우저 기반 도구

\n

도구가 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 서버

\n

MCP 서버는 항상 SYNAPSE_MIND_KEY 환경 변수를 통해 헤더 인증을\n사용합니다 — 속도 제한이 적용되지 않습니다.

\n

대량 가져오기

\n

대량 작업(예: 1000개 메모리 가져오기)의 경우, 항상 헤더 인증을\n사용하십시오. ?key=를 통한 대량 가져오기는 1분 이내에 속도 제한에\n도달합니다.

\n

할당량 (마인드 수준)

\n

현재 저장소 크기나 메모리 수에 대한 마인드별 할당량이 없습니다. 모든\n제한은 데이터 수준이 아닌 인증/IP 수준에 있습니다. 이는 다중 테넌트\n공정성을 위해 향후 변경될 수 있습니다.

\n

사용량 모니터링

\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","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"]}