Limity
Ile zapytań możesz wysłać.
Zapytania na minutę
Każdy endpoint pozwala na stałą liczbę zapytań na minutę. Dla endpointów danych i odczytu konta wszystkie klucze i tokeny konta liczą się razem. Liczy się każde zapytanie, także odrzucone.
| Endpoint | Co | Limit na minutę |
|---|---|---|
| fetch-organization | Profil firmy | 60 |
| fetch-person | Profil osoby | 60 |
| search-organizations | Wyszukiwanie i eksport | 60 |
| fetch-document | Dokumenty | 5 |
| signals | Signals | 60 |
| account | Odczyt konta | 30 |
| account, auth/tokens | Zarządzanie bearer tokenami; tworzenie, zmiana i usuwanie kluczy, monitorów i endpointów webhooków | 10 |
| account/webhook-endpoints | Weryfikacja i test endpointu webhooka, rotacja secretu | 6 |
Wyszukiwanie, dokumenty i Signals dzielą wspólną pulę 60 zapytań na minutę. Dokumenty mają dodatkowo własny, mniejszy limit.
Zapytania zapisujące do konta, Monitoring i webhooków wliczają się też do limitu konta. Te same liczby są w „Kosztach i limitach” na stronie każdego endpointu.
Limity są takie same w każdej subskrypcji kredytów. Jeśli potrzebujesz więcej zapytań na minutę, umowa Enterprise może dać ci wyższe limity.
Limit osiągnięty
Ponad limit API odpowiada 429. Nagłówek Retry-After mówi, po ilu sekundach możesz znów wysyłać zapytania. Ta sama liczba jest w polu retry_after.
Każda odpowiedź pokazuje w nagłówkach, ile masz jeszcze zapasu:
| Nagłówek | Znaczenie | Przykład |
|---|---|---|
| X-RateLimit-Limit | Limit tego endpointu na minutę. |
30 |
| X-RateLimit-Remaining | Ile zapytań jest jeszcze możliwych w tej minucie. |
0 |
| Retry-After |
Tylko przy 429: sekundy do następnego możliwego zapytania.
|
17 |
| X-RateLimit-Reset |
Tylko przy 429: chwila, od której możesz kontynuować, jako czas Unix.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Gdy wysyłasz wiele zapytań, obserwuj X-RateLimit-Remaining i zwolnij sam, zanim API odpowie 429. Zapytanie ponad limit nic nie kosztuje.
Timeouty
Większość odpowiedzi przychodzi w ciągu kilku sekund. Tryb AI, feature news, pobrania w czasie rzeczywistym, fetch-person i dokumenty trwają dłużej, bo dokumenty i dane w czasie rzeczywistym pobieramy bezpośrednio z rejestru.
Ustaw timeout klienta na co najmniej 120 sekund, zwłaszcza dla trybu czasu rzeczywistego, fetch-person i dokumentów. Za krótki timeout przerywa zapytania, które właśnie miały się zakończyć.
Dla dokumentów jest też async=true: API odpowiada od razu 202 i pobiera dokument w tle, zobacz fetch-document.
408, przy dokumentach 504 z Retry-After. Nic nie jest naliczane. Powtórz zapytanie nieco później. Jeśli w trybie czasu rzeczywistego nie uda się tylko pobranie na żywo, dostajesz profil firmy z zapisanymi danymi, bez dopłaty.
Ponowienie bez podwójnego naliczenia
Jeśli twój klient przerwie zapytanie, może ono mimo to zakończyć się po naszej stronie i zostać naliczone. Z nagłówkiem Idempotency-Key ponowienie nic wtedy nie kosztuje.
Wybierz osobny klucz dla każdego zapytania i wyślij go bez zmian przy ponowieniu. Klucz ma od 1 do 128 znaków: litery, cyfry, kropka, podkreślnik, dwukropek i łącznik, zaczynając od litery lub cyfry.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: TWOJ_KLUCZ_API" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Przypadek | Endpointy danych | Monitoring i webhooki |
|---|---|---|
| Klucz wymagany | nie, opcjonalny |
tak, inaczej 428
|
| Okno | 24 godziny | 24 godziny |
| Ten sam klucz, te same parametry | Wynik ponownie, bez naliczenia | Zapisana odpowiedź z jej statusem |
| Ten sam klucz, inne parametry |
422 idempotency_key_reused |
409 idempotency_conflict |
| Po błędzie | Klucz pozostaje wolny | Wraca ten sam błąd, potrzebny nowy klucz |
Endpointy danych
fetch-organization, fetch-person, search-organizations i fetch-document przyjmują klucz opcjonalnie. Jeśli powtórzysz zapytanie z tym samym kluczem i tymi samymi parametrami w ciągu 24 godzin, dostajesz wynik ponownie, bez naliczenia.
Pierwsza odpowiedź ma nagłówek Idempotency-Status: created, każde ponowienie Idempotency-Status: replayed i meta.request_credit_cost: 0. Ponowienie nie wymaga salda.
Klucz wiąże dopiero dostarczony wynik. Po błędzie możesz więc dalej używać tego samego klucza. Ten sam klucz z innymi parametrami daje 422 z idempotency_key_reused. Endpointy danych ignorują klucz w innym formacie, więc trzymaj się dokładnie formatu.
signals nie przyjmuje klucza idempotencji.
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 i webhooki
Zapytania zapisujące do /v1/account/monitors, /v1/account/webhook-endpoints i /v1/account/webhook-deliveries wymagają klucza. Bez niego API odpowiada 428; klucz w złym formacie daje 400.
W ciągu 24 godzin ten sam klucz z tymi samymi parametrami zwraca zapisaną odpowiedź z jej statusem, plus Idempotency-Status: replayed. Dotyczy to też błędów. Do nowej próby, np. ponownej weryfikacji, używasz więc nowego klucza.
Ten sam klucz z innymi parametrami daje 409 z idempotency_conflict. Jeśli pierwsze zapytanie jeszcze trwa, dostajesz 409 z idempotency_in_progress.
Planuj ponowienia
Nie każdy błąd jest wart drugiej próby. Postępuj tak:
- Ponawiaj:
408,429poRetry-Afteri5xx. Między próbami czekaj za każdym razem dłużej, np. 2, 4 i 8 sekund, i przestań po kilku próbach. - Najpierw popraw, potem wyślij ponownie:
400,401,402,403,404i422. To samo zapytanie wysłane ponownie da ten sam wynik. - Wysyłaj klucz idempotencji przy płatnych zapytaniach. Wtedy ponowienie po przerwaniu nic nie kosztuje.