Chyby a limity
Co API vrací, když požadavek neprojde, a jaké limity platí. Chyby konkrétní operace uvádí reference u ní.
Formát chyby
Chyba je objekt JSON s českou zprávou v poli error. Některé chyby mají strojový kód v poli code. Chyby validace záznamu přidávají pole errors se zprávami podle názvu pole, některé operace podrobnosti v poli problems nebo issues. Neplatný JSON (400), chyba aplikace (500) a požadavek nad 21 MB (413 od webového serveru) českou zprávu nemají a vracejí stránku HTML. U 400 a 500 s hlavičkou Accept: application/json přijde jen {"status": …, "error": …}.
{
"error": "Číslo účtu už existuje",
"errors": { "code": ["už existuje"] }
}{
"error": "Tento API klíč smí jen číst",
"code": "READ_ONLY_KEY"
}Stavové kódy
| Stav | Kdy |
|---|---|
| 200, 201, 204 | Úspěch. 201 vrací založení záznamu, 204 smazání bez těla odpovědi. |
| 400 | Chybí povinný parametr nebo soubor, parametr má neplatný tvar, nebo je neplatné datum. Neplatný JSON vrací 400 bez zprávy Salda. |
| 401 | Chybí přihlášení (AUTH_REQUIRED) nebo je API klíč neplatný či zrušený (INVALID_API_KEY). |
| 403 | Klíč jen pro čtení u zápisu (READ_ONLY_KEY), zápis z cizího webu nebo zápis se session cookie bez X-Saldo (CROSS_SITE), nedostatečná role, nebo operace jen pro prohlížeč. |
| 404 | Záznam neexistuje, nebo patří firmě, ve které nejste přijatým členem. |
| 405 | Metoda není povolená, například HEAD u balíčku pro účetní. |
| 409 | Firma už sestavuje jiný balíček pro účetní (PACKAGE_BUSY). |
| 413 | Soubor je větší, než operace dovolí (jiné operace vracejí 422, viz reference), nebo celý požadavek přesahuje 21 MB. |
| 422 | Data neprošla validací nebo pravidlem účetnictví, například uzamčené období, vystavený doklad nebo nesouhlasící zůstatky výpisu. |
| 429 | Příliš mnoho požadavků (RATE_LIMITED). |
| 500 | Chyba aplikace. Známé případy popisuje Známé chyby vracející 500. |
| 502 | Externí služba neodpověděla, například ARES (ARES_UNAVAILABLE) nebo portál Moje daně. |
Kódy chyb
| Kód | Stav | Význam |
|---|---|---|
AUTH_REQUIRED | 401 | Požadavek nemá API klíč ani přihlášení. |
INVALID_API_KEY | 401 | API klíč neexistuje nebo je zrušený. |
READ_ONLY_KEY | 403 | Klíč jen pro čtení poslal jiný požadavek než GET nebo HEAD, nebo stahuje XML hlášení JMHZ. |
CROSS_SITE | 403 | Zápis přišel z jiného webu, nebo zápis se session cookie nemá X-Saldo: 1. U balíčku pro účetní a XML hlášení JMHZ i stažení z jiného webu. |
RATE_LIMITED | 429 | Překročený limit požadavků klíče nebo vyhledávání firem. |
PACKAGE_BUSY | 409 | Balíček pro účetní se ve firmě právě sestavuje. |
PDF_PASSWORD_REQUIRED | 422 | Výpis v PDF je zašifrovaný a chybí nebo nesedí heslo. |
IDENTIFIED_KH | 422 | Identifikovaná osoba kontrolní hlášení nepodává. |
MONTHLY_KH | 422 | Právnická osoba podává kontrolní hlášení za měsíc, ne za čtvrtletí. |
INVALID_ICO | 422 | IČO při vyhledání firmy (/lookup/{ico}) není platné. |
NOT_FOUND | 200 | Vyhledání firmy v ARES nic nenašlo; odpověď je úspěšná s found: false. |
ARES_UNAVAILABLE | 502 | ARES teď neodpovídá (/lookup/{ico}; vyhledání u kontaktu vrací 502 bez kódu). |
Ostatní chyby kód nemají, například uzamčené období. Rozlišujte je stavovým kódem a textem v poli error, který se ale může změnit.
Limity
| Limit | Hodnota |
|---|---|
| Požadavky s API klíčem | 600 za minutu na klíč, zvlášť pro každou skupinu cest (například /documents…, /bank_transactions…); přihlášení v prohlížeči tento limit nemá |
Vyhledání firmy podle IČO (/lookup/{ico}) | 40 za minutu na uživatele |
| Aktivní API klíče | 20 na uživatele |
| Velikost celého požadavku | 21 MB (limit serveru) |
| Částky ve veřejných kalkulátorech | nejvýš 15 číslic před desetinnou čárkou, delší se berou jako 0; výpočty daní, mezd a cest jen pro roky, pro které Saldo má sazby (GET /rates) |
Rok v parametru year | 2000–2100; číslo mimo rozsah se zarovná na nejbližší mez |
Limity velikosti a počtu souborů popisuje Soubory, importy a opakování. Limity počtu řádků v seznamech jsou v Formátu dat.
Známé chyby vracející 500
Některé neplatné vstupy dnes skončí chybou 500 místo srozumitelné 4xx. Týká se to například neplatného daňového období (period, month, quarter), neznámé hodnoty kind při založení dokladu nebo bankovního účtu a ověření kontaktu v registru plátců DPH, když registr DIČ najde. Případy u daní a registru plátců uvádí reference v tabulce Chyby této operace. Posílejte proto jen hodnoty z výčtů a rozsahů, které reference uvádí.