Skip to content

Chybové kódy ​

Každá chybová odpověď je JSON s polem error (u některých cest navíc strojový code):

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

Dvě nejčastější chyby naživo: 409 (mapa se mezitím změnila) a 400 (pole, které API nezná — hláška vyjmenuje povolená a poradí ekvivalent).

Tabulka ​

KódKdyPříklad hláškyCo s tím
400Chybí 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 vrcholPolož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.
401Chybí hlavička Authorization, token není kb_user_… / fm_user_…, klíč je neznámý, nebo vypršelNeplatný API klíč. · Chybí API klíč (Authorization: Bearer kb_user_...).Zkontrolujte hlavičku, pak jestli klíč někdo nerotoval nebo mu nevypršela platnost.
402Jen 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.
403Klíč 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žeraChybí 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í.
404Mapa, uzel, rodič, událost, připomínka, šablona nebo pravidlo neexistuje — nebo patří někomu jinémuMapa nebyla nalezena.API ty dva případy záměrně nerozlišuje, aby se přes něj nedalo zjišťovat, která ID existují.
409base_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.
410Volání /v1/tasks* — úkolové endpointy byly odstraněnyRozhraní /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.
413Tě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.
429Př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 minutToo many invalid API keys, try later.Zpomalte a zkuste to znovu. Čtení a zápisy se počítají zvlášť.
503Jen 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:

Totéž 409 z pohledu editoru: když mapu změní skript nebo asistent, kolega s otevřeným editorem dostane na výběr.

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 isError a 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.md k tomu má odstavec Typical failures (401, 402, 503, resource … does not match → KB_PUBLIC_URL).

Souvisí ​

Open source pod licencí MIT · © Tengo s.r.o.