Error codes
Every error response is JSON with an error field (some routes add a machine-readable code):
{ "error": "Invalid API key." }The message arrives in the language of the account the key belongs to; the status code is the part to branch on, not the text.
Table
| Code | When | Example message | What to do |
|---|---|---|---|
| 400 | A required field is missing or malformed (title, base_updated, an unknown status, a bad date), a field the endpoint does not know (the message lists the allowed ones and hints at the equivalent: priority → planned_on, room → calendar, until → end_day), planned_on outside today…+7, an unknown owner, more than 200 items in one call, structural caps (20 keys, 50 rules per map, 50 templates, 100 calendars, 2,000 events), a reminder on a node without a deadline or in the past, deleting the apex | Item "…" has unknown fields: priority. Allowed fields: … · Too many API keys — revoke an old one first (max 20). | Fix the request. Retrying it unchanged will not help. |
| 401 | No Authorization header, a token that is not kb_user_… / fm_user_…, an unknown key, or an expired key | Invalid API key. · Missing API key (Authorization: Bearer kb_user_...). | Check the header, then check whether the key was rotated or has expired. |
| 402 | Hosted instance only: a write after the trial ended or with a paused plan (reads keep working) | The trial has ended. Your data is safe and can be exported… | Nothing in code — the plan is sorted out in the app. |
| 403 | A read key called a write endpoint; or the map's share level allows no more than the status of your own nodes (work, read); rules and the run log for readers and collaborators; somebody else's rule template; somebody else's event; time off for a colleague without the admin/manager role | The status field is missing (todo, in_progress, done). · Only an admin or manager can enter time off for a colleague. | Per the message: either a read_write key, or a higher share level from the map owner. Rotating the key does not change the share level. |
| 404 | The map, node, parent, event, reminder, template or rule does not exist — or belongs to somebody else | Map not found. | The API deliberately does not distinguish the two, so it cannot be used to probe which ids exist. |
| 409 | base_updated does not match the map's current version; for a room booking, an overlap with another booking (the body carries collision and next_free) | The map was edited elsewhere in the meantime. Please reload it. | Somebody changed the map in the meantime. Re-read it, re-apply your change, send it again. For a room, take next_free. |
| 410 | A call to /v1/tasks* — the task endpoints were removed | The /v1/tasks endpoints were removed — a task is a node with an assignee or deadline. Use /v1/maps/{id}/nodes… | Create or update a node through /v1/maps/{id}/nodes. |
| 413 | Request body over 2 MB (also on /mcp) | Request body too large. | Split the work into more calls; 200 nodes per call is the hard cap anyway. |
| 429 | Over the rate limit — 120 reads or 30 writes per minute per key; GET /v1/portfolio 60 per minute per user; on /mcp 20 invalid keys from one IP in 10 minutes | Too many invalid API keys, try later. | Back off and retry. Reads and writes are counted separately. |
| 503 | Hosted instance only: the instance is being moved to another server (code: "migrating") | We're moving your instance to your own server… | Wait a few minutes and retry. |
The two that surprise people
404 instead of 403. Asking for someone else's map does not tell you it exists. This is on purpose: a 403 would confirm the id is real, which turns the API into an id oracle.
409 is normal, not a failure. Two clients editing one map — an assistant and a colleague with the editor open — will hit it. The correct handling is always: re-read the map, re-apply, retry. Never "force the write". The colleague in the editor sees the same thing from the other side as the conflict dialog:
Do not retry a 400 or a 403
They mean the request is wrong, not that the moment was wrong. An automated retry loop on either one just burns your rate limit.
How errors look through MCP
The MCP server sits on the same routes, but the assistant does not see status codes:
- An unknown tool argument is rejected at call time (
-32602, in English): Unknown argument "priority" for update_node. Allowed: … There is no "priority" in killBottleneck — priority is expressed by the plan planned_on… - A server error (400/403/404/409…) arrives as a tool result flagged
isErrorwith the message text in the account's language — the assistant should repeat it to the user, not quietly try something else. - A 409 on write is only seen on a genuine race — the server reads the map version itself before writing and returns the current tree in the reply.
- 401 / 429 on
/mcp: an invalid key, or 20 invalid attempts from one IP in 10 minutes. The/agent-setup.mdguide has a Typical failures paragraph for these (401, 402, 503, resource … does not match →KB_PUBLIC_URL).
Related
- REST API — endpoints and limits
- MCP server — When the agent does not connect
- Collaboration and conflicts — the conflict from the editor's side

