Errors and permissions
Goono Open API error codes, key scopes, project roles, and plan constraints
When a tool fails, the result has isError: true and text in this shape. The MCP server appends a guidance sentence per code for the LLM to relay.
Goono API <status> <path> — [<code>] <message> — <guidance> — (requestId: ...)Include the requestId when contacting Goono support. Branch on code, not message. Codes may be added in a backward-compatible way; unknown codes are passed through without guidance.
Error codes
| Status | Code | Meaning · what to do |
|---|---|---|
| 400 | BAD_REQUEST | Invalid input |
| 400 | OFFSET_TOO_LARGE | offset above 10,000. Narrow the query with filters |
| 400 | INVALID_PAGINATION_SCOPE | offset in search requires exactly one section |
| 401 | INVALID_API_KEY | Header missing, malformed, or invalid. Check the key |
| 401 | KEY_EXPIRED | Expired. Issue a new key |
| 401 | KEY_DEACTIVATED | Revoked. Issue a new key |
| 403 | INSUFFICIENT_SCOPE | A write tool was called with a read key. Use a write scoped key |
| 403 | WORKSPACE_PLAN_INACTIVE | Plan lapsed. Not a key problem; reissuing will not help |
| 403 | FORBIDDEN_WORKSPACE | Key was issued for another workspace, or you are not a member |
| 403 | FORBIDDEN_PROJECT | Insufficient project role (drafts and writes need RW; locked deletion needs admin) |
| 403 | FORBIDDEN_BY_IP_ACL | Network issue. Outside the IP allowlist; lists work but details are blocked |
| 403 | REVIEW_REQUIRED_PROJECT | Notes cannot be moved into a project that requires review |
| 404 | NOT_FOUND | May have been deleted or moved after listing. Re-locate with search |
| 404 | FILE_NOT_FOUND | File missing in storage |
| 404 | THUMBNAIL_NOT_AVAILABLE | No thumbnail for variant: thumb |
| 409 | FOLDER_NOT_EMPTY | Notes remain or a GitHub repo is linked. Move notes out first |
| 409 | FILE_NOT_READY | Still converting or upload failed. Retry later |
| 413 | FILE_TOO_LARGE | Over 512KB. The MCP server turns this into a normal result carrying only the size |
| 429 | RATE_LIMITED | Rate limit exceeded. Retry shortly |
| 502 | FILE_UNAVAILABLE | Storage fetch or decryption failed. Retry |
| 504 | FILE_TIMEOUT | Storage did not respond in time. Retry |
The MCP server itself returns only three HTTP errors: 401 INVALID_API_KEY when the X-Goono-Key header is missing or its prefix is not gno_live_ / gno_test_, 404 for any path other than /mcp, and 405 for methods other than POST.
Permission model
Tools see exactly what the key owner can see in Goono. A key cannot grant more than its owner has.
Key scopes
| Scope | Covers |
|---|---|
read | The 14 read tools |
write | read + create_folder, rename_folder, delete_folder, move_note |
Check apiKey.scopes in get_me.
Project roles
myAuthType in list_projects and members[].authType in get_project carry the role.
| Action | Required role |
|---|---|
| Read notes and reviews, search | Member |
| Read research drafts | RW |
| Create, rename, delete folders; move notes | RW (+ write scope) |
| Move a note to another project | ADMIN on the source project + RW on the target |
| Delete a folder in a deletion-locked project | Admin |
Plans
- Check
workspace.planTypeinget_me. - When the plan lapses, every call returns
403 WORKSPACE_PLAN_INACTIVE. The same key works again once the plan is renewed. - Without an active plan, the
notesByOcrTextsection ofsearchis empty. TheocrTextfilter oflist_noteshas no plan restriction. - IP allowlists apply only to ENTERPRISE_PLUS workspaces with ACL enabled.