Reference

Errors and limits

The shape of an error response, status codes, error codes and request limits.

Updated 30 Oct 2026

Error shape

An error always has an HTTP status code and a body with at least these fields:

JSON

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

Decide based on statusCode and, when present, code. The message text is for people and can change; many messages are in Czech.

Status codes

Status	When	What to do
`400`	The request failed validation.	Fix the data using the `validation` field.
`401`	The API key or token is missing or invalid.	Check the `Authorization` header.
`402`	The company’s plan does not include this, code `plan_limit`.	Change the plan in Settings under Subscription.
`403`	Not allowed: a read-only key or connection (`insufficient_scope`), or the user’s role.	Use a key with the `full` scope, or ask the company owner for another role.
`404`	The object does not exist or belongs to another company.	Check the ID.
`405`	You sent something other than `POST` to `/mcp`.	The MCP server is stateless, so use `POST`.
`409`	The action does not fit the object’s state, such as issuing an issued invoice.	Load the object’s current state.
`429`	You went over a request limit.	Wait as the `retry-after` header says.
`5xx`	An error on our side.	Try again later; a `GET` can be repeated right away.

Error codes

Where a status alone is not enough, the body has a code:

Code	Status	Meaning
`insufficient_scope`	`403`	The API key or OAuth connection is read-only.
`send_scope_required`	`403`	The key or connection has no permission to send. Full access does not include it.
`remote_send_off`	`403`	Sending through the API and MCP is not on in this company.
`send_owner_only`	`403`	Only a connection of the company’s owner may send.
`remote_send_order_limit`, `remote_send_daily_limit`, `remote_send_filing_limit`	`403`	Over a limit the owner set. The prepared send stays, and a person can confirm it in the app.
`remote_send_currency`	`403`	The limits are in crowns, so a person confirms an order in another currency in the app.
`remote_send_dashboard_only`	`403`	Turning sending on or raising a limit happens only in the app.
`plan_limit`	`402`	The plan lacks a feature, or a limit such as documents a month or users is used up. The body may name the `feature`.

Validation errors

When the body or parameters fail validation, you get a 400 with details per field:

JSON

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

Duplicates

Some conflicts tell you which object they collided with:

JSON

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

MCP errors

The /mcp endpoint answers in JSON-RPC. Without a valid token you get a 401 with a WWW-Authenticate header and the body { "jsonrpc": "2.0", "error": { "code": -32000, "message": "…" }, "id": null }. When a tool’s underlying operation fails, the tool result is marked as an error and its text holds the HTTP status and body.

Limits

These limits apply per IP address.

Operation	Limit
Sign-up `POST /auth/register`	10 an hour
Resend verification `POST /auth/resend-verification`	5 an hour
Sign-in `POST /auth/login`	10 a minute
Session refresh `POST /auth/refresh`	300 a minute
Password reset and e-mail verification	6 a minute
Password and two-factor changes, account export	6 a minute
Deleting an account	3 a minute
Viewing an invitation / accepting it	30 / 10 a minute
`POST /oauth/register`	20 an hour
`GET /oauth/authorize`	60 a minute
OAuth sign-in and two-factor steps	10 a minute
OAuth consent	30 a minute
`POST /oauth/token`, `POST /oauth/revoke`	60 a minute
Public document links	120 a minute

The public /v1 and /mcp have no fixed per-key limit today. Please still call them sensibly: don’t try to overload them, and expect that a limit may be added. Respond to a 429 by waiting as the retry-after header says.

A request body can be at most 1 MiB, except for operations that take a file:

Operation	Body limit
Importing a file (POHODA XML, XLSX, CSV)	60 MiB
Uploading to the inbox (the file itself up to 25 MB)	40 MiB
Importing a bank statement	30 MB
Uploading a company logo	4 MiB

Files travel as base64, so they grow by about a third on the way.