Reference

Chyby a limity

Tvar chybové odpovědi, stavové kódy, kódy chyb a limity požadavků.

Aktualizováno 30. 10. 2026

Tvar chyby

Chyba má vždy stavový kód HTTP a tělo alespoň s těmito poli:

JSON

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Not found"
}

Rozhodujte se podle statusCode a případně podle code. Text message je pro lidi a může se měnit; řada zpráv je česky.

Stavové kódy

Stav	Kdy	Co dělat
`400`	Požadavek neprošel ověřením.	Opravte data podle pole `validation`.
`401`	API klíč nebo token chybí nebo je neplatný.	Zkontrolujte hlavičku `Authorization`.
`402`	Tarif firmy to nezahrnuje, kód `plan_limit`.	Změňte tarif v Nastavení v části Předplatné.
`403`	Není povoleno: klíč nebo připojení jen pro čtení (`insufficient_scope`), nebo role uživatele.	Použijte klíč s rozsahem `full` nebo požádejte vlastníka firmy o jinou roli.
`404`	Objekt neexistuje nebo patří jiné firmě.	Zkontrolujte ID.
`405`	Na `/mcp` jste poslali něco jiného než `POST`.	MCP server je bezstavový, používejte `POST`.
`409`	Akce neodpovídá stavu objektu, třeba vystavení už vystavené faktury.	Načtěte aktuální stav objektu.
`429`	Překročili jste limit požadavků.	Počkejte podle hlavičky `retry-after`.
`5xx`	Chyba na naší straně.	Zkuste to později; `GET` můžete zopakovat hned.

Kódy chyb

Kde samotný stav nestačí, je v těle code:

Kód	Stav	Význam
`insufficient_scope`	`403`	API klíč nebo připojení OAuth je jen pro čtení.
`send_scope_required`	`403`	Klíč nebo připojení nemá oprávnění odesílat. Plný přístup ho neobsahuje.
`remote_send_off`	`403`	Odesílání přes API a MCP není ve firmě zapnuté.
`send_owner_only`	`403`	Odesílat smí jen připojení vlastníka firmy.
`remote_send_order_limit`, `remote_send_daily_limit`, `remote_send_filing_limit`	`403`	Překročený limit, který nastavil vlastník. Příprava zůstává a člověk ji může potvrdit v aplikaci.
`remote_send_currency`	`403`	Limity jsou v korunách, příkaz v jiné měně potvrzuje člověk v aplikaci.
`remote_send_dashboard_only`	`403`	Zapnout odesílání nebo zvýšit limit lze jen v aplikaci.
`plan_limit`	`402`	Tarif nemá danou funkci, nebo je vyčerpaný limit, třeba dokladů za měsíc nebo uživatelů. Tělo může uvádět `feature`.

Chyby ověření

Když tělo nebo parametry neprojdou ověřením, dostanete 400 s podrobnostmi po polích:

JSON

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "validation": {
    "formErrors": [],
    "fieldErrors": { "issueDate": ["Invalid"] }
  }
}

Duplicity

Některé konflikty řeknou, s jakým objektem se střetly:

JSON

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "…",
  "duplicate": true,
  "existingId": "rin_…"
}

Chyby MCP

Koncový bod /mcp odpovídá v JSON-RPC. Bez platného tokenu dostanete 401 s hlavičkou WWW-Authenticate a tělem { "jsonrpc": "2.0", "error": { "code": -32000, "message": "…" }, "id": null }. Když selže operace pod nástrojem, je výsledek nástroje označený jako chyba a v textu je stav HTTP a tělo odpovědi.

Limity

Tyto limity platí pro každou IP adresu.

Operace	Limit
Registrace `POST /auth/register`	10 za hodinu
Opětovné ověření `POST /auth/resend-verification`	5 za hodinu
Přihlášení `POST /auth/login`	10 za minutu
Obnovení relace `POST /auth/refresh`	300 za minutu
Reset hesla a ověření e-mailu	6 za minutu
Změna hesla a dvoufázového ověření, export účtu	6 za minutu
Smazání účtu	3 za minutu
Zobrazení pozvánky / její přijetí	30 / 10 za minutu
`POST /oauth/register`	20 za hodinu
`GET /oauth/authorize`	60 za minutu
Přihlášení a dvoufázové ověření v OAuth	10 za minutu
Souhlas v OAuth	30 za minutu
`POST /oauth/token`, `POST /oauth/revoke`	60 za minutu
Veřejné odkazy na doklady	120 za minutu

Veřejné /v1 a /mcp dnes nemají pevný limit na klíč. Přesto je volejte rozumně: nesnažte se je přetížit a počítejte s tím, že limit může přibýt. Na 429 reagujte čekáním podle hlavičky retry-after.

Tělo požadavku může mít nejvýš 1 MiB, kromě operací, které přijímají soubor:

Operace	Limit těla
Import souboru (POHODA XML, XLSX, CSV)	60 MiB
Nahrání do K vyřízení (samotný soubor do 25 MB)	40 MiB
Import bankovního výpisu	30 MB
Nahrání loga firmy	4 MiB

Soubory putují jako base64, takže po cestě narostou asi o třetinu.