# Errors & limits (https://systemhub.com/docs/concepts/errors-and-limits)

> Part of systemHUB Docs · Connect: Settings → AI Gateway in systemHUB · Auth: OAuth (scoping is workspace-level today — see Getting started) · MCP tools: 48 · Full corpus: https://systemhub.com/llms-full.txt

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 into multiple documents.** Note `edit_*` replaces the whole `content` field, so "writing in sections" means resending an ever-larger body — it reaches the ceiling sooner, not later. |
| 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). |
| Document renders as **visible tag soup** (literal `<h2>` characters on screen) | You sent **HTML-escaped content** (`&lt;h2&gt;` instead of `<h2>`); the API stores it verbatim and returns success | Send raw HTML. Read the document back after writing to confirm rendering. |
| `403` "Company not found" fetching a **share link** externally | Known issue — the share endpoint can't resolve the workspace from the bare URL (verified 28 Jul 2026) | Tracked with the product team; test a share link before promising it to an outside party. See [Sharing & links](/docs/concepts/sharing-and-links). |

## 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 follows the token, not the person.** Reads and writes are scoped to the identity on the workspace's most recently generated AI Gateway token — not necessarily whoever is connected (known issue, fix in progress). "Document not found" can simply mean *that identity* can't see it.
- **No seat provisioning, no deletes, no workspace-wide analytics** via the MCP — see [Known limits](/docs/#known-limits) and the [changelog](/docs/changelog) for what's recently landed (document-level member assignment and per-document activity logs are now available).

## 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.