에러 코드와 권한
Goono Open API 에러 코드, 키 스코프, 프로젝트 역할, 플랜 제약
도구가 실패하면 isError: true와 함께 아래 형식의 텍스트가 옵니다. MCP 서버는 코드별로 LLM이 사용자에게 할 안내 문구를 덧붙입니다.
Goono API <status> <path> — [<code>] <message> — <안내> — (requestId: ...)requestId는 Goono 지원 문의 시 함께 알려 주세요. 분기는 message가 아니라 code로 합니다. 코드는 하위호환으로 추가될 수 있으며 알 수 없는 코드는 안내 없이 그대로 전달됩니다.
에러 코드
| 상태 | 코드 | 의미 · 대응 |
|---|---|---|
| 400 | BAD_REQUEST | 입력 오류 |
| 400 | OFFSET_TOO_LARGE | offset 상한 10,000 초과. 필터로 범위를 좁히세요 |
| 400 | INVALID_PAGINATION_SCOPE | search의 offset은 sections가 하나일 때만 |
| 401 | INVALID_API_KEY | 헤더 누락 또는 형식·값 오류. 키를 확인하세요 |
| 401 | KEY_EXPIRED | 만료. 재발급 |
| 401 | KEY_DEACTIVATED | 폐기됨. 재발급 |
| 403 | INSUFFICIENT_SCOPE | read 키로 쓰기 도구를 호출. write 스코프 키가 필요 |
| 403 | WORKSPACE_PLAN_INACTIVE | 플랜 만료. 키 문제가 아니라 재발급으로 풀리지 않음 |
| 403 | FORBIDDEN_WORKSPACE | 키가 발급된 워크스페이스가 아니거나 멤버가 아님 |
| 403 | FORBIDDEN_PROJECT | 프로젝트 권한 부족(연구초안·쓰기는 RW, 삭제 잠금은 관리자) |
| 403 | FORBIDDEN_BY_IP_ACL | 네트워크 문제. IP 허용목록 밖. 목록엔 보이는데 상세가 막힘 |
| 403 | REVIEW_REQUIRED_PROJECT | 점검 필수 프로젝트로는 노트를 바로 옮길 수 없음 |
| 404 | NOT_FOUND | 목록 조회 뒤 삭제·이동됐을 수 있음. search로 재탐색 |
| 404 | FILE_NOT_FOUND | 저장소에 파일 없음 |
| 404 | THUMBNAIL_NOT_AVAILABLE | variant: thumb 썸네일 없음 |
| 409 | FOLDER_NOT_EMPTY | 노트가 남아 있거나 GitHub 연동 중. 노트를 먼저 옮긴 뒤 삭제 |
| 409 | FILE_NOT_READY | 변환·업로드 미완료. 잠시 후 재시도 |
| 413 | FILE_TOO_LARGE | 512KB 초과. MCP 서버가 에러 대신 크기만 담은 정상 결과로 바꿔 줌 |
| 429 | RATE_LIMITED | Rate limit 초과. 잠시 후 재시도 |
| 502 | FILE_UNAVAILABLE | 저장소 조회·복호화 실패. 재시도 |
| 504 | FILE_TIMEOUT | 저장소 응답 지연. 재시도 |
MCP 서버 자체가 내는 HTTP 에러는 셋뿐입니다: X-Goono-Key 헤더가 없거나 접두사가 gno_live_ / gno_test_가 아니면 401 INVALID_API_KEY, /mcp 외 경로는 404, POST 외 메서드는 405.
권한 모델
도구가 볼 수 있는 범위는 키 소유자의 Goono 권한과 정확히 같습니다. 키에 권한을 더 줄 수는 없습니다.
키 스코프
| 스코프 | 범위 |
|---|---|
read | 조회 14종 |
write | read + create_folder, rename_folder, delete_folder, move_note |
get_me의 apiKey.scopes로 확인합니다.
프로젝트 역할
list_projects의 myAuthType과 get_project의 members[].authType이 역할 정보입니다.
| 작업 | 필요한 역할 |
|---|---|
| 노트·점검 조회, 검색 | 멤버 |
| 연구초안 조회 | RW |
| 폴더 생성·이름 변경·삭제, 노트 이동 | RW (+ write 스코프) |
| 프로젝트 간 노트 이동 | 출발 프로젝트 ADMIN + 도착 프로젝트 RW |
| 삭제 잠금 프로젝트의 폴더 삭제 | 관리자 |
플랜
get_me의workspace.planType으로 확인합니다.- 플랜이 만료되면 모든 호출이
403 WORKSPACE_PLAN_INACTIVE입니다. 플랜이 갱신되면 같은 키로 다시 동작합니다. - 활성 플랜이 없으면
search의notesByOcrText섹션은 빈 결과입니다.list_notes의ocrText필터에는 플랜 제한이 없습니다. - IP 허용목록은 ENTERPRISE_PLUS 플랜에서 ACL을 켠 워크스페이스에만 적용됩니다.