Limite
Câte cereri poți face.
Cereri pe minut
Fiecare endpoint permite un număr fix de cereri pe minut. Pentru endpointurile de date și pentru citirea contului, toate cheile și tokenurile unui cont se socotesc împreună. Fiecare cerere contează, chiar și una respinsă.
| Endpoint | Ce | Limită pe minut |
|---|---|---|
| fetch-organization | Profil companie | 60 |
| fetch-person | Profil persoană | 60 |
| search-organizations | Căutare & Export | 60 |
| fetch-document | Documente | 5 |
| signals | Signals | 60 |
| account | Citirea contului | 30 |
| account, auth/tokens | Gestionarea bearer tokenurilor; crearea, modificarea și ștergerea cheilor, monitoarelor și endpointurilor webhook | 10 |
| account/webhook-endpoints | Verificarea și testarea unui endpoint webhook, rotirea secretului | 6 |
Căutarea, documentele și Signals împart o cotă de 60 cereri pe minut. Documentele au în plus propria limită, mai mică.
Cererile de scriere pentru cont, Monitoring și webhookuri se socotesc și la limita contului. Aceleași cifre sunt listate la „Costuri și limite” pe pagina fiecărui endpoint.
Limitele sunt aceleași în orice abonament de credite. Dacă ai nevoie de mai multe cereri pe minut, un contract Enterprise îți poate oferi limite mai mari.
Limită atinsă
Peste limită, API-ul răspunde cu 429. Headerul Retry-After îți spune după câte secunde poți trimite din nou cereri. Același număr se află în câmpul retry_after.
Fiecare răspuns arată în headere cât spațiu mai ai:
| Header | Semnificație | Exemplu |
|---|---|---|
| X-RateLimit-Limit | Limita pe minut a acestui endpoint. |
30 |
| X-RateLimit-Remaining | Câte cereri mai sunt posibile în acest minut. |
0 |
| Retry-After |
Doar la 429: secundele până la următoarea cerere posibilă.
|
17 |
| X-RateLimit-Reset |
Doar la 429: momentul în care poți continua, ca timp Unix.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Când trimiți multe cereri, urmărește X-RateLimit-Remaining și încetinește singur înainte ca API-ul să răspundă cu 429. O cerere peste limită nu costă nimic.
Timeouturi
Majoritatea răspunsurilor sosesc în câteva secunde. Modul AI, funcția news, preluările în timp real, fetch-person și documentele durează mai mult, pentru că documentele și datele în timp real le preluăm direct din registru.
Setează timeoutul clientului la cel puțin 120 de secunde, mai ales pentru Timp real, fetch-person și documente. Un timeout prea scurt întrerupe cereri care tocmai urmau să se termine.
Pentru documente există și async=true: API-ul răspunde imediat cu 202 și preia documentul în fundal, vezi fetch-document.
408, la documente 504 cu Retry-After. Nu se facturează nimic. Reîncearcă cererea puțin mai târziu. Dacă eșuează doar preluarea live pentru Timp real, primești profilul de companie cu datele salvate, fără suprataxa pentru Timp real.
Reîncercare fără taxare dublă
Dacă clientul tău întrerupe o cerere, ea se poate totuși finaliza la noi și poate fi facturată. Cu headerul Idempotency-Key, reîncercarea nu mai costă nimic.
Alege o cheie separată pentru fiecare cerere și trimite-o neschimbată la reîncercare. O cheie are 1 până la 128 de caractere: litere, cifre, punct, underscore, două puncte și cratimă, începând cu o literă sau o cifră.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: CHEIA_TA_API" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Caz | Endpointuri de date | Monitoring și webhookuri |
|---|---|---|
| Cheie obligatorie | nu, opțional |
da, altfel 428
|
| Interval | 24 de ore | 24 de ore |
| Aceeași cheie, aceiași parametri | Rezultatul din nou, fără facturare | Răspunsul salvat cu statusul lui |
| Aceeași cheie, alți parametri |
422 idempotency_key_reused |
409 idempotency_conflict |
| După o eroare | Cheia rămâne liberă | Revine aceeași eroare, e nevoie de o cheie nouă |
Endpointuri de date
fetch-organization, fetch-person, search-organizations și fetch-document acceptă cheia opțional. Dacă repeți o cerere cu aceeași cheie și aceiași parametri în 24 de ore, primești din nou rezultatul, fără facturare.
Primul răspuns poartă headerul Idempotency-Status: created, fiecare reîncercare Idempotency-Status: replayed și meta.request_credit_cost: 0. O reîncercare nu are nevoie de sold.
Doar un rezultat livrat leagă cheia. După o eroare poți deci folosi în continuare aceeași cheie. Aceeași cheie cu alți parametri dă 422 cu idempotency_key_reused. Endpointurile de date ignoră o cheie în alt format, deci respectă exact formatul.
signals nu acceptă o cheie de idempotență.
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 webhookuri
Cererile de scriere către /v1/account/monitors, /v1/account/webhook-endpoints și /v1/account/webhook-deliveries au nevoie de cheie. Fără ea, API-ul răspunde cu 428; o cheie în format greșit dă 400.
În 24 de ore, aceeași cheie cu aceiași parametri returnează răspunsul salvat cu statusul lui, plus Idempotency-Status: replayed. Asta se aplică și erorilor. Pentru o încercare nouă, de ex. o nouă verificare, folosești deci o cheie nouă.
Aceeași cheie cu alți parametri dă 409 cu idempotency_conflict. Dacă prima cerere încă rulează, primești 409 cu idempotency_in_progress.
Planifică reîncercările
Nu orice eroare merită o a doua încercare. Iată cum procedezi:
- Reîncearcă:
408,429dupăRetry-Afterși5xx. Așteaptă de fiecare dată mai mult între încercări, de exemplu 2, 4 și 8 secunde, și oprește-te după câteva încercări. - Corectează întâi, apoi retrimite:
400,401,402,403,404și422. Aceeași cerere trimisă din nou aduce același rezultat. - Trimite o cheie de idempotență cu cererile plătite. Atunci o reîncercare după o întrerupere nu costă nimic.