Skip to content

Error codes ​

Every error response is JSON with an error field (some routes add a machine-readable code):

json
{ "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.

The two most common errors live: 409 (the map changed in the meantime) and 400 (a field the API does not know — the message lists the allowed ones and suggests the equivalent).

Table ​

CodeWhenExample messageWhat to do
400A 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 apexItem "…" 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.
401No Authorization header, a token that is not kb_user_… / fm_user_…, an unknown key, or an expired keyInvalid API key. · Missing API key (Authorization: Bearer kb_user_...).Check the header, then check whether the key was rotated or has expired.
402Hosted 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.
403A 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 roleThe 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.
404The map, node, parent, event, reminder, template or rule does not exist — or belongs to somebody elseMap not found.The API deliberately does not distinguish the two, so it cannot be used to probe which ids exist.
409base_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.
410A call to /v1/tasks* — the task endpoints were removedThe /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.
413Request 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.
429Over 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 minutesToo many invalid API keys, try later.Back off and retry. Reads and writes are counted separately.
503Hosted 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:

The same 409 from the editor's point of view: when a script or the assistant changes the map, a colleague with the editor open gets to choose.

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 isError with 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.md guide has a Typical failures paragraph for these (401, 402, 503, resource … does not match → KB_PUBLIC_URL).

Open source under the MIT license · © Tengo s.r.o.