# Chyby a limity · Dokumentace DameDokladu

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

Source: https://damedoklad.cz/docs/errors-and-limits/

# Chyby a limity

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

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