Errors and limits

Problem documents, error codes, rate limits and timeouts.

Problem documents

Errors are RFC 9457 application/problem+json documents with a stable code:

{
  "title": "Service Unavailable",
  "status": 503,
  "detail": "not found, but these sources are not fresh: rpo",
  "code": "unavailable",
  "reason": "source_stale"
}

`code`	Status	Meaning
`invalid_request`	400, 422	A parameter is missing or out of range; `errors` lists the details.
`invalid_identifier`	400	The lookup id is not an IČO, DIČ or IČ DPH.
`fuzzy_disabled`	400	`mode=fuzzy` on an instance where it is off.
`unauthorized`	401	No key, or an unknown key.
`forbidden`	403	A natural person by DIČ on an instance with anonymous access.
`not_found`	404	Not found, and every consulted source is fresh.
`rate_limited`	429	Too many requests; see `Retry-After`.
`unavailable`	503	See `reason`: `bootstrapping`, `setup` (the operator has not confirmed the instance yet), `source_stale`, `timeout`, `database`, or `overloaded` (the instance is at its capacity: retry after `Retry-After`).

Treat 503 as “unknown”: retry later, and never as “not found”.

Rate limits

Each caller (a key, or a client IP in anonymous mode) has a token bucket, per instance:

Limit	Default	Variable
Requests	20 per second, burst 40	`REGISTER_RATE_PER_SECOND`, `REGISTER_RATE_BURST`
Fuzzy searches	1 per 5 s, burst 2	`REGISTER_FUZZY_EVERY`
Fuzzy searches running at once	1 per instance	`REGISTER_FUZZY_CONCURRENCY`

Over a limit, the answer is 429 with Retry-After in seconds. Nothing is queued.

Timeouts

Query	Default	Variable
Default search and lookup	3 s	`REGISTER_QUERY_TIMEOUT`
Fuzzy search	2 s	`REGISTER_FUZZY_TIMEOUT`

A query over its timeout answers 503 with reason timeout.