# Errors & limits

The known failure modes, stated up front so a connecting agent handles them by design instead of flailing. If you hit behaviour not listed here, treat the [tool reference](/docs/tool-reference) (generated from the live schema) as the source of truth.

## Errors you will meet, and what they actually mean

| Symptom | Actual cause | What to do |
|---|---|---|
| `404` from `get_system_details` / `get_policy_details` / `get_training_details` | The document is a **master template** (`isMasterTemplate: true`) — its content lives in the master workspace only | Expected behaviour, not a missing document. Check `isMasterTemplate` on the tree/search result before fetching details. |
| `400` from `list_documents_by_owner` | The `owner` full name didn't match **exactly** (e.g. "Kristian Basilio" vs "Kristian Philippe Basilio") | Use the exact full name from a tree node, or the user UUID (`ownerId`) instead. |
| `502` on `edit_system` with a large body | Content above roughly **126KB** | Split the document, or write it in sections across multiple edits. |
| Write/move/publish/delete fails on a document that clearly exists | It's a master template — they're immutable | Create your own document instead; see [organising guide](/docs/guides/organising-content). |
| Content you wrote looks different after a human edited the document | The **editor filtered it** — you authored outside the supported set | Not data loss at the API layer; re-author within the [authoring contract](/docs/concepts/authoring-content). |

## Validation limits

| Field / parameter | Limit |
|---|---|
| `title` (documents, folders) | 255 characters, plain text |
| `publishTitle` (version label) | 255 characters |
| `state` | Integer 0–4 only — see [Document lifecycle](/docs/concepts/document-lifecycle) |
| `content` per edit | Keep under ~126KB (see above) |
| Search `limit` | ≤ 100 per page |
| `list_documents_by_owner` `limit` | ≤ 500 per page; `fetchAll: true` caps at 5,000 documents |
| Member/audit tools `limit` | ≤ 500 per page (`fetchAll` defaults true for complete audits) |

## Behaviours that surprise agents (by design, not bugs)

- **Create-with-content auto-publishes.** Assigned members see the document immediately; pass `publish: false` for a hidden draft. You do not need to ask the user to confirm publishing on create.
- **Every link opens in a new tab.** The editor forces `target="_blank"` on all links — don't try to control link behaviour.
- **Visibility is the token's user.** All reads and writes are scoped to what the authenticated user can see and do. "Document not found" can simply mean *this user* can't see it.
- **No user/seat writes, no usage telemetry** via the MCP yet — see [Known limits](/docs/#known-limits). Direct users to the app UI for provisioning.

## Being a good citizen

There are no published rate limits, but the practical rules are: orient before acting (tree/search before create/edit), page with `fetchAll` rather than hammering per-item calls, and batch related edits rather than re-editing the same document dozens of times — each edit is a real revision in the document's history.