Limitek
Hány kérést indíthatsz.
Kérések percenként
Minden végpont percenként rögzített számú kérést enged. Az adatvégpontoknál és a fiók olvasásánál egy fiók összes kulcsa és tokenje együtt számít. Minden kérés számít, az elutasított is.
| Végpont | Mi | Limit percenként |
|---|---|---|
| fetch-organization | Cégprofil | 60 |
| fetch-person | Személyprofil | 60 |
| search-organizations | Keresés és export | 60 |
| fetch-document | Dokumentumok | 5 |
| signals | Signals | 60 |
| account | A fiók olvasása | 30 |
| account, auth/tokens | Bearer tokenek kezelése; kulcsok, monitorok és webhook-végpontok létrehozása, módosítása és törlése | 10 |
| account/webhook-endpoints | Webhook-végpont ellenőrzése és tesztelése, a secret cseréje | 6 |
A keresés, a dokumentumok és a Signals közös keretet használ: percenként 60 kérés. A dokumentumoknak ezen felül saját, kisebb limitjük is van.
A fiókra, a Monitoringra és a webhookokra vonatkozó írási kérések a fióklimitbe is beleszámítanak. Ugyanezek a számok minden végpont oldalán a „Költségek és limitek” alatt is szerepelnek.
A limitek minden kredit-előfizetésben azonosak. Ha percenként több kérésre van szükséged, egy Enterprise-szerződés magasabb limiteket adhat.
Limit elérve
A limit felett az API 429-cel válaszol. A Retry-After header megmondja, hány másodperc múlva küldhetsz újra kéréseket. Ugyanez a szám a retry_after mezőben is szerepel.
Minden válasz headerekben mutatja, mennyi mozgástered maradt:
| Header | Jelentés | Példa |
|---|---|---|
| X-RateLimit-Limit | Ennek a végpontnak a percenkénti limitje. |
30 |
| X-RateLimit-Remaining | Hány további kérés lehetséges ebben a percben. |
0 |
| Retry-After |
Csak 429 esetén: másodpercek a következő lehetséges kérésig.
|
17 |
| X-RateLimit-Reset |
Csak 429 esetén: az időpont, amikor folytathatod, Unix-időként.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Ha sok kérést küldesz, figyeld az X-RateLimit-Remaining headert, és lassíts magadtól, mielőtt az API 429-cel válaszolna. A limit feletti kérés nem kerül semmibe.
Időkorlátok
A legtöbb válasz néhány másodpercen belül megérkezik. Az AI mód, a news funkció, a valós idejű lekérések, a fetch-person és a dokumentumok tovább tartanak, mert a dokumentumokat és a valós idejű adatokat közvetlenül a nyilvántartásból kérjük le.
Állítsd a kliensed időkorlátját legalább 120 másodpercre, különösen a valós idejű módhoz, a fetch-personhöz és a dokumentumokhoz. A túl rövid időkorlát olyan kéréseket szakít meg, amelyek éppen befejeződnének.
Dokumentumokhoz ott van az async=true is: az API azonnal 202-vel válaszol, és a háttérben kéri le a dokumentumot, lásd fetch-document.
408-at kapsz, dokumentumoknál 504-et Retry-After headerrel. Semmit nem számolunk fel. Próbáld újra a kérést kicsit később. Ha csak a valós idejű mód élő lekérése nem sikerül, a cégprofilt a tárolt adatokkal kapod meg, a valós idejű mód felára nélkül.
Újrapróbálás dupla terhelés nélkül
Ha a kliensed megszakít egy kérést, az nálunk még befejeződhet, és felszámolhatjuk. Az Idempotency-Key headerrel az újrapróbálás ilyenkor nem kerül semmibe.
Minden kéréshez válassz külön kulcsot, és küldd változatlanul az újrapróbáláskor. Egy kulcs 1–128 karakterből áll: betűk, számjegyek, pont, aláhúzás, kettőspont és kötőjel, betűvel vagy számjeggyel kezdve.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: AZ_API_KULCSOD" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Eset | Adatvégpontok | Monitoring és webhookok |
|---|---|---|
| Kulcs kötelező | nem, opcionális |
igen, különben 428
|
| Időablak | 24 óra | 24 óra |
| Ugyanaz a kulcs, ugyanazok a paraméterek | Újra az eredmény, terhelés nélkül | Tárolt válasz a státuszával |
| Ugyanaz a kulcs, más paraméterek |
422 idempotency_key_reused |
409 idempotency_conflict |
| Hiba után | A kulcs szabad marad | Ugyanaz a hiba jön vissza, új kulcs kell |
Adatvégpontok
A fetch-organization, a fetch-person, a search-organizations és a fetch-document opcióként elfogadja a kulcsot. Ha egy kérést 24 órán belül ugyanazzal a kulccsal és ugyanazokkal a paraméterekkel megismételsz, újra megkapod az eredményt, terhelés nélkül.
Az első válasz az Idempotency-Status: created headert hordozza, minden újrapróbálás az Idempotency-Status: replayed headert és a meta.request_credit_cost: 0 értéket. Az újrapróbáláshoz nem kell egyenleg.
Csak a kiszállított eredmény köti le a kulcsot. Hiba után tehát ugyanazt a kulcsot használhatod tovább. Ugyanaz a kulcs más paraméterekkel 422-t ad idempotency_key_reused kóddal. Az adatvégpontok a más formátumú kulcsot figyelmen kívül hagyják, ezért pontosan tartsd be a formátumot.
A signals nem fogad el idempotency kulcsot.
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 és webhookok
A /v1/account/monitors, a /v1/account/webhook-endpoints és a /v1/account/webhook-deliveries írási kéréseihez kell a kulcs. Nélküle az API 428-cal válaszol; a rossz formátumú kulcs 400-at ad.
24 órán belül ugyanaz a kulcs ugyanazokkal a paraméterekkel a tárolt választ adja vissza a státuszával, plusz Idempotency-Status: replayed headerrel. Ez a hibákra is érvényes. Új kísérlethez, például ismételt ellenőrzéshez, ezért új kulcsot használsz.
Ugyanaz a kulcs más paraméterekkel 409-et ad idempotency_conflict kóddal. Ha az első kérés még fut, 409-et kapsz idempotency_in_progress kóddal.
Az újrapróbálások megtervezése
Nem minden hiba ér meg egy második kísérletet. Így járj el:
- Próbáld újra:
408,429aRetry-Afterután és5xx. Minden alkalommal várj tovább a kísérletek között, például 2, 4 és 8 másodpercet, és néhány kísérlet után állj le. - Előbb javíts, aztán küldd újra:
400,401,402,403,404és422. Ugyanazt a kérést újra elküldve ugyanazt az eredményt kapod. - A fizetős kérésekhez küldj idempotency kulcsot. Így a megszakítás utáni újrapróbálás nem kerül semmibe.