속도 제한 및 할당량

Synapse는 남용을 방지하면서 정상적인 사용을 방해하지 않는 단순하고 예측 가능한 속도 제한 정책을 가지고 있습니다.

속도 제한 정책

속도 제한 헤더

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

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

제한을 초과한 경우:

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

속도 제한에 도달한 경우

429를 받은 경우:

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

   # 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초 대기 후 재시도.

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

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

• 보안: 쿼리 파라미터는 서버 접근 로그, 브라우저 기록, Referer 헤더에 기록됩니다. 사용량을 제한하면 노출이 줄어듭니다.
• 성능: 쿼리 파라미터 인증은 IP 기반 속도 제한기(요청당 Redis 조회)가 필요하여 지연이 추가됩니다. 헤더 인증은 이를 생략합니다.
• 남용 방지: 유출된 ?key= URL은 공유되어 남용될 수 있습니다. IP 제한으로 피해 범위를 제한합니다.

권장 패턴

LLM 에이전트

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

브라우저 기반 도구

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

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

대량 가져오기

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

할당량 (마인드 수준)

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

사용량 모니터링

# 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
• 오류 및 오류 처리