Chybové stavy API

Odpovědi API nemají jeden společný tvar. Zpracovávejte HTTP stav, Content-Type a popis konkrétní operace.

Úspěšná odpověď

Nejčastěji jde o JSON s "status": "success" a daty v poli data. Některé operace, například export kontaktů, vracejí "result": "success". Importy vracejí text, PDF a exporty soubor. Tvar úspěšné odpovědi vždy ověřte na stránce operace.

Podoby chyb

status a error

Validační chyby, typicky s HTTP 400:

{"status":"error","error":"Název je povinný."}

status a message

Chybné tělo požadavku, přihlášení a oprávnění:

{"status":"error","message":"Neplatný JSON."}

Chybějící nebo neplatný token vrací HTTP 401 s "message":"Unauthorized", volání z nepovolené IP adresy HTTP 403 s "message":"Forbidden".

Prostý text

Importy mohou vrátit text/plain s textem začínajícím ERROR:. Export dokladů s neplatnou kombinací parametrů může vrátit text i s HTTP 200. Nedekódujte proto každou odpověď automaticky jako JSON.

HTTP stavy

Stav	Význam
200	Úspěch. U importů a exportů zkontrolujte i tělo odpovědi.
201	Vytvořený záznam, například nový API přístup.
400	Neplatné JSON tělo nebo parametry.
401	Chybí platný API token.
403	Nepovolená IP adresa nebo chybějící modul či oprávnění.
404	Neexistující cesta nebo záznam.
405	Cesta existuje, ale metoda není povolená.
500	Chyba serveru. Tělo nemusí být JSON.

Doporučený postup při chybě

Ověřte metodu, cestu, parametry a Content-Type podle stránky operace.
Při 401 zkontrolujte token a jeho platnost, při 403 povolené IP adresy a moduly.
Čtěte pole error nebo message, případně text odpovědi.
Zápisy po nejasné chybě automaticky neopakujte, nejdřív ověřte, jestli se neprovedly.