Chybové kódy

Každá chybová odpověď je JSON s jediným polem error:

{ "error": "Neplatný API klíč." }

Text přijde v jazyce účtu, kterému klíč patří; větvit se má podle stavového kódu.

Tabulka

Kód	Kdy	Co s tím
400	Chybí nebo je špatně povinné pole — žádný title, žádný base_updated, neznámý status, špatné datum expirace, víc než 200 položek v jednom volání	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	Zkontrolujte hlavičku, pak jestli klíč někdo nerotoval nebo mu nevypršela platnost.
403	Klíč s rozsahem read volal zápisový endpoint	Vytvořte nebo zrotujte klíč s rozsahem read_write.
404	Mapa, uzel, rodič nebo úkol neexistuje — nebo patří někomu jinému	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	Někdo mapu mezitím změnil. Načtěte ji znovu, znovu aplikujte svou změnu a pošlete to znovu.
413	Tělo požadavku přes 2 MB	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íč	Zpomalte a zkuste to znovu. Čtení a zápisy se počítají zvlášť.

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

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.