Limity
Kolik požadavků můžeš odeslat.
Požadavky za minutu
Každý endpoint povoluje pevný počet požadavků za minutu. U datových endpointů a čtení účtu se počítají všechny klíče a tokeny účtu dohromady. Počítá se každý požadavek, i odmítnutý.
| Endpoint | Co | Limit za minutu |
|---|---|---|
| fetch-organization | Profil firmy | 60 |
| fetch-person | Profil osoby | 60 |
| search-organizations | Vyhledávání a export | 60 |
| fetch-document | Dokumenty | 5 |
| signals | Signals | 60 |
| account | Čtení účtu | 30 |
| account, auth/tokens | Správa bearer tokenů; vytváření, úprava a mazání klíčů, monitorů a webhook endpointů | 10 |
| account/webhook-endpoints | Ověření a test webhook endpointu, rotace secretu | 6 |
Vyhledávání, dokumenty a Signals sdílejí kvótu 60 požadavků za minutu. Dokumenty mají navíc vlastní, nižší limit.
Zápisové požadavky na účet, Monitoring a webhooky se započítávají i do limitu účtu. Stejná čísla jsou uvedena v části „Náklady a limity“ na stránce každého endpointu.
Limity jsou stejné v každém předplatném kreditů. Pokud potřebuješ víc požadavků za minutu, smlouva Enterprise ti může dát vyšší limity.
Limit dosažen
Nad limitem API odpovídá 429. Header Retry-After ti řekne, za kolik sekund můžeš požadavky posílat znovu. Stejné číslo je v poli retry_after.
Každá odpověď ukazuje v headerech, kolik prostoru ti zbývá:
| Header | Význam | Příklad |
|---|---|---|
| X-RateLimit-Limit | Limit tohoto endpointu za minutu. |
30 |
| X-RateLimit-Remaining | Kolik dalších požadavků je v této minutě možné. |
0 |
| Retry-After |
Jen u 429: sekundy do dalšího možného požadavku.
|
17 |
| X-RateLimit-Reset |
Jen u 429: čas, kdy můžeš pokračovat, jako unixový čas.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Když posíláš mnoho požadavků, sleduj X-RateLimit-Remaining a zpomal sám, než API odpoví 429. Požadavek nad limit nic nestojí.
Časové limity
Většina odpovědí přijde během několika sekund. AI režim, funkce news, načtení v reálném čase, fetch-person a dokumenty trvají déle, protože dokumenty a data v reálném čase načítáme přímo z rejstříku.
Nastav časový limit svého klienta alespoň na 120 sekund, zejména pro režim v reálném čase, fetch-person a dokumenty. Příliš krátký časový limit přeruší požadavky, které se právě chystají skončit.
U dokumentů je navíc async=true: API odpoví hned s 202 a načte dokument na pozadí, viz fetch-document.
408, u dokumentů 504 s Retry-After. Nic se neúčtuje. Zopakuj požadavek o něco později. Pokud selže jen živé načtení v režimu v reálném čase, dostaneš profil firmy s uloženými daty, bez příplatku za režim v reálném čase.
Opakování bez dvojího účtování
Pokud tvůj klient požadavek přeruší, u nás může přesto doběhnout a být zaúčtován. S headerem Idempotency-Key pak opakování nic nestojí.
Pro každý požadavek zvol vlastní klíč a pošli ho při opakování beze změny. Klíč má 1 až 128 znaků: písmena, číslice, tečka, podtržítko, dvojtečka a pomlčka, začíná písmenem nebo číslicí.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TVUJ_API_KLIC" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Případ | Datové endpointy | Monitoring a webhooky |
|---|---|---|
| Klíč povinný | ne, volitelný |
ano, jinak 428
|
| Okno | 24 hodin | 24 hodin |
| Stejný klíč, stejné parametry | Výsledek znovu, bez účtování | Uložená odpověď s jejím stavem |
| Stejný klíč, jiné parametry |
422 idempotency_key_reused |
409 idempotency_conflict |
| Po chybě | Klíč zůstává volný | Vrátí se stejná chyba, je potřeba nový klíč |
Datové endpointy
fetch-organization, fetch-person, search-organizations a fetch-document přijímají klíč volitelně. Pokud požadavek zopakuješ se stejným klíčem a stejnými parametry do 24 hodin, dostaneš výsledek znovu, bez účtování.
První odpověď nese header Idempotency-Status: created, každé opakování Idempotency-Status: replayed a meta.request_credit_cost: 0. Opakování nepotřebuje žádný zůstatek.
Klíč váže jen doručený výsledek. Po chybě tedy můžeš stejný klíč dál používat. Stejný klíč s jinými parametry dá 422 s idempotency_key_reused. Klíč v jiném formátu datové endpointy ignorují, drž se proto přesně formátu.
signals idempotency klíč nepřijímá.
1{2 "error": "idempotency_key_reused",3 "message": "This Idempotency-Key was already used with different parameters.",4 "meta": {5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
Monitoring a webhooky
Zápisové požadavky na /v1/account/monitors, /v1/account/webhook-endpoints a /v1/account/webhook-deliveries klíč vyžadují. Bez něj API odpoví 428; klíč ve špatném formátu dá 400.
Do 24 hodin vrátí stejný klíč se stejnými parametry uloženou odpověď s jejím stavem, plus Idempotency-Status: replayed. To platí i pro chyby. Pro nový pokus, například opětovné ověření, proto použij nový klíč.
Stejný klíč s jinými parametry dá 409 s idempotency_conflict. Pokud první požadavek ještě běží, dostaneš 409 s idempotency_in_progress.
Plánuj opakování
Ne každá chyba stojí za druhý pokus. Postupuj takto:
- Opakuj:
408,429poRetry-Aftera5xx. Mezi pokusy čekej pokaždé déle, například 2, 4 a 8 sekund, a po několika pokusech přestaň. - Nejdřív oprav, pak pošli znovu:
400,401,402,403,404a422. Opětovné odeslání stejného požadavku přinese stejný výsledek. - U placených požadavků posílej idempotency klíč. Pak opakování po přerušení nic nestojí.