Chybové kódy
Každá chybová odpověď je JSON s polem error (u některých cest navíc strojový code):
{ "error": "Neplatný API klíč." }Text přijde v jazyce účtu, kterému klíč patří; větvit se má podle stavového kódu, ne podle textu.
Tabulka
| Kód | Kdy | Příklad hlášky | Co s tím |
|---|---|---|---|
| 400 | Chybí nebo je špatně povinné pole (title, base_updated, neznámý status, špatné datum), pole, které cesta nezná (hláška vyjmenuje povolená a napoví ekvivalent: priority → planned_on, room → calendar, until → end_day), planned_on mimo okno dnes…+7, neznámý owner, přes 200 položek v jednom volání, strukturální stropy (20 klíčů, 50 pravidel na mapu, 50 šablon, 100 kalendářů, 2 000 událostí), připomínka k uzlu bez termínu nebo v minulosti, pokus smazat vrchol | Položka „…“ má neznámá pole: priority. Povolená pole: … · Příliš mnoho API klíčů — zrušte nejdřív některý starý (max 20). | Opravte požadavek. Opakovat ho beze změny nepomůže. |
| 401 | Chybí hlavička Authorization, token není kb_user_… / fm_user_…, klíč je neznámý, nebo vypršel | Neplatný API klíč. · Chybí API klíč (Authorization: Bearer kb_user_...). | Zkontrolujte hlavičku, pak jestli klíč někdo nerotoval nebo mu nevypršela platnost. |
| 402 | Jen hostovaná instance: zápis po konci zkušebky nebo s pozastaveným tarifem (čtení funguje dál) | Zkušební doba skončila. Vaše data zůstávají a jdou vyexportovat… | Nic v kódu — tarif se řeší v aplikaci. |
| 403 | Klíč s rozsahem read volal zápis; nebo úroveň sdílení mapy nedovolí víc než stav vlastních uzlů (work, read); pravidla a log běhů pro čtenáře a spolupracovníky; cizí šablona pravidla; cizí událost; nepřítomnost za kolegu bez role správce/manažera | Chybí pole status (todo, in_progress, done). · Nepřítomnost za kolegu zapisuje jen správce nebo manažer. | Podle hlášky: buď klíč s rozsahem read_write, nebo vyšší úroveň sdílení od vlastníka mapy. Rotace klíče úroveň sdílení nezmění. |
| 404 | Mapa, uzel, rodič, událost, připomínka, šablona nebo pravidlo neexistuje — nebo patří někomu jinému | Mapa nebyla nalezena. | API ty dva případy záměrně nerozlišuje, aby se přes něj nedalo zjišťovat, která ID existují. |
| 409 | base_updated nesedí na aktuální verzi mapy; u rezervace místnosti překryv s jinou rezervací (tělo nese collision a next_free) | Mapa byla mezitím upravena z jiného místa. Načtěte ji prosím znovu. | Někdo mapu mezitím změnil. Načtěte ji znovu, znovu aplikujte svou změnu a pošlete to znovu. U místnosti vezměte next_free. |
| 410 | Volání /v1/tasks* — úkolové endpointy byly odstraněny | Rozhraní /v1/tasks bylo odstraněno — úkol je uzel s řešitelem nebo termínem. Používejte /v1/maps/{id}/nodes… | Založte nebo upravte uzel přes /v1/maps/{id}/nodes. |
| 413 | Tělo požadavku přes 2 MB (platí i pro /mcp) | Request body too large. | Rozdělte práci na víc volání; 200 uzlů na volání je stejně tvrdý strop. |
| 429 | Přes limit — 120 čtení nebo 30 zápisů za minutu na klíč; GET /v1/portfolio 60 za minutu na uživatele; na /mcp 20 neplatných klíčů z jedné IP za 10 minut | Too many invalid API keys, try later. | Zpomalte a zkuste to znovu. Čtení a zápisy se počítají zvlášť. |
| 503 | Jen hostovaná instance: stěhování na jiný server (code: "migrating") | Přesouváme vaši instanci na váš vlastní server… | Počkejte pár minut a zkuste to znovu. |
Dvě věci, které lidi překvapí
404 místo 403. Dotaz na cizí mapu vám neprozradí, že existuje. Je to záměr: 403 by potvrdilo, že je ID skutečné, a udělalo by z API věštírnu na ID.
409 je normální stav, ne selhání. Dva klienti nad jednou mapou — asistent a kolega s otevřeným editorem — na něj narazí. Správná reakce je vždycky: načíst mapu znovu, znovu aplikovat, zopakovat. Nikdy „vynutit zápis“. Kolega v editoru vidí totéž z druhé strany jako dialog konfliktu:
400 ani 403 neopakujte
Znamenají, že je špatně požadavek, ne že byla špatná chvíle. Automatická smyčka opakování na kterémkoli z nich jen spálí váš limit.
Jak chyby vypadají přes MCP
MCP server stojí nad stejnými cestami, ale asistent nevidí stavové kódy:
- Neznámý argument nástroje je odmítnutý už při volání (
-32602, anglicky): Unknown argument "priority" for update_node. Allowed: … There is no "priority" in killBottleneck — priority is expressed by the plan planned_on… - Chyba serveru (400/403/404/409…) přijde jako výsledek nástroje s příznakem
isErrora textem hlášky v jazyce účtu — asistent ji má zopakovat uživateli, ne tiše zkusit něco jiného. - 409 při zápisu asistent uvidí jen při skutečném souběhu — server si verzi mapy před zápisem načítá sám a v odpovědi vrátí aktuální strom.
- 401 / 429 na
/mcp: neplatný klíč, nebo 20 neplatných pokusů z jedné IP za 10 minut. Návod/agent-setup.mdk tomu má odstavec Typical failures (401, 402, 503, resource … does not match →KB_PUBLIC_URL).
Souvisí
- REST API — endpointy a limity
- MCP server — Když se agent nepřipojí
- Spolupráce a konflikty — konflikt z pohledu editoru

