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 vrací 400 s kódem INVALID_JSON. Chyba aplikace (500) a požadavek nad 21 MB (413 od webového serveru) českou zprávu nemají a vracejí stránku HTML; u 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, je neplatné datum, nebo tělo není platný JSON (INVALID_JSON). |
| 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. |
PAYROLL_ACCESS | 403 | Mzdy a údaje zaměstnanců: volající je editor nebo Jen čtení bez přístupu ke mzdám (zapíná ho vlastník nebo účetní). |
SUBMITTER_ONLY | 403 | Volající má ve firmě roli Nahrává doklady (submitter) a operace je mimo vlastní koncepty přijatých dokladů, jejich přílohy, přidělené žádosti o podklady a údaje firmy; nebo chce doklad vystavit či založit jiný druh. |
PAYROLL_ALWAYS | 422 | Přístup ke mzdám nejde vypnout vlastníkovi ani účetní, vidí mzdy vždy. |
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
Neplatné daňové období (period, month, quarter) vrací 422, neznámá hodnota kind při založení dokladu nebo bankovního účtu 422 a neplatné datum 400. Chybou 500 dnes končí stažení hlášení JMHZ s více než 1 500 formuláři pracovněprávních vztahů (reference u operace). Posílejte jen hodnoty z výčtů a rozsahů, které reference uvádí.