Rate limit
API 키 단위 분당 한도와 초과 시 동작
Rate limit은 Goono Open API가 API 키 단위, 분당, 버킷별 독립으로 적용합니다. MCP 서버 자체에는 별도 제한이 없습니다. 초당 한도나 워크스페이스 단위 한도는 없습니다.
| 버킷 | 분당 한도 | 해당 도구 |
|---|---|---|
default | 300 | 조회·점검 도구 전부 (get_me, list_*, get_*, search) |
content | 60 | get_note_file · get_review_file · get_research_draft(본문 포함 시) |
write | 60 | create_folder · rename_folder · delete_folder · move_note |
한도는 운영 설정으로 조정될 수 있습니다. 현재 값은 응답 헤더로 확인할 수 있습니다.
응답 헤더
Open API의 모든 정상 응답에 잔여량이 실립니다.
| 헤더 | 의미 |
|---|---|
X-RateLimit-Bucket | 이 요청이 속한 버킷 |
X-RateLimit-Limit | 버킷의 분당 한도 |
X-RateLimit-Remaining | 현재 윈도에서 남은 횟수 |
X-RateLimit-Reset | 윈도가 초기화되는 시각(epoch 초) |
초과 시 동작
한도를 넘으면 Open API가 429 + { "code": "RATE_LIMITED", ... }와 Retry-After(초) 헤더로 응답합니다.
MCP 클라이언트가 실제로 받는 것
MCP 서버는 HTTP 헤더를 클라이언트에 전달하지 않습니다. 클라이언트(LLM)가 받는 것은 isError: true인 도구 결과 하나이며 텍스트는 아래 형식입니다.
Goono API 429 /workspaces/... — [RATE_LIMITED] rate limit exceeded — 요청 한도를 초과했다. 잠시 후 재시도할 것. — (requestId: ...)Retry-After 값은 도구 결과에 포함되지 않습니다. LLM은 잠시 후 재시도하라는 안내만 받습니다.
제한에 걸렸을 때
- 파일 조회를 병렬로 몰아치지 마세요.
content버킷이 분당 60회라 가장 먼저 소진됩니다. 서버 instructions에도 "필요한 파일만 순차로"가 들어 있습니다. - 연구초안 목록을 훑을 때는
includeContent: false로 본문 전송을 생략하면content버킷을 쓰지 않습니다. list_notes필터로 범위를 좁히세요. 전체 목록을 받아 LLM이 거르는 것보다tags·extensions·writtenAfter필터가 호출 수를 줄입니다.search는 미리보기로 시작하세요.sections를 생략하면 5섹션을 한 번에 최대 20건씩 받습니다. 드릴다운은 섹션 하나를 지정해 최대 50건씩 페이징합니다.- 워크스페이스가 여럿이면 키도 여럿입니다. 한도는 키 단위이므로 서로 영향을 주지 않습니다.