# 속도 제한 및 할당량

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

## 속도 제한 정책

| 인증 방법 | 제한 | 범위 |
|-------------|-------|-------|
| Mind Key (`Authorization: Bearer`) | **없음** | 마인드별 |
| Mind Key (`?key=`) | 분당 60회 | IP별 |
| JWT (`Authorization: Bearer`) | **없음** | 사용자별 |
| 공용 엔드포인트 | **없음** | 전역 |

> [!TIP]
> **가능하면 항상 `Authorization: Bearer` 헤더를 사용하십시오.** 속도
> 제한이 없습니다. `?key=`는 사용자 정의 헤더를 설정할 수 없는 도구에만
> 사용하십시오.

## 속도 제한 헤더

`?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 헤더로 전환** (권장):
   ```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. **또는 `Retry-After`초 대기** 후 재시도.

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

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

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

## 권장 패턴

### LLM 에이전트

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

### 브라우저 기반 도구

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

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

### 대량 가져오기

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

## 할당량 (마인드 수준)

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

## 사용량 모니터링

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

## 다음 단계

- [Authentication](/docs/getting-started/authentication)
- [오류 및 오류 처리](/docs/api/errors)