Grenser
Hvor mange forespørsler du kan gjøre.
Forespørsler per minutt
Hvert endepunkt tillater et fast antall forespørsler per minutt. For dataendepunktene og for lesing av kontoen teller alle nøkler og tokens i en konto sammen. Hver forespørsel teller, også en avvist.
| Endepunkt | Hva | Grense per minutt |
|---|---|---|
| fetch-organization | Firmaprofil | 60 |
| fetch-person | Personprofil | 60 |
| search-organizations | Søk & eksport | 60 |
| fetch-document | Dokumenter | 5 |
| signals | Signals | 60 |
| account | Lese kontoen | 30 |
| account, auth/tokens | Administrere bearer-tokens; opprette, endre og slette nøkler, monitorer og webhook-endepunkter | 10 |
| account/webhook-endpoints | Verifisere og teste et webhook-endepunkt, bytte secret | 6 |
Søk, dokumenter og Signals deler en kvote på 60 forespørsler per minutt. Dokumenter har i tillegg sin egen, lavere grense.
Skriveforespørsler til kontoen, Monitoring og webhooks teller også mot kontogrensen. De samme tallene står under «Kostnader og grenser» på hver endepunktside.
Grensene er de samme i hvert kredittabonnement. Trenger du flere forespørsler per minutt, kan en Enterprise-avtale gi deg høyere grenser.
Grensen er nådd
Over grensen svarer API-et med 429. Headeren Retry-After sier etter hvor mange sekunder du kan sende forespørsler igjen. Det samme tallet står i feltet retry_after.
Hvert svar viser i headere hvor mye rom du har igjen:
| Header | Betydning | Eksempel |
|---|---|---|
| X-RateLimit-Limit | Grensen per minutt for dette endepunktet. |
30 |
| X-RateLimit-Remaining | Hvor mange forespørsler som fortsatt er mulige dette minuttet. |
0 |
| Retry-After |
Bare med 429: sekunder til neste mulige forespørsel.
|
17 |
| X-RateLimit-Reset |
Bare med 429: tidspunktet da du kan fortsette, som Unix-tid.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Når du sender mange forespørsler, følger du med på X-RateLimit-Remaining og bremser selv før API-et svarer med 429. En forespørsel over grensen koster ingenting.
Tidsavbrudd
De fleste svar kommer innen noen sekunder. AI-modus, funksjonen news, sanntidshentinger, fetch-person og dokumenter tar lengre tid, fordi vi henter dokumenter og sanntidsdata direkte fra registeret.
Sett tidsavbruddet i klienten din til minst 120 sekunder, særlig for Sanntid, fetch-person og dokumenter. Et for kort tidsavbrudd avbryter forespørsler som nesten er ferdige.
For dokumenter finnes også async=true: API-et svarer med en gang med 202 og henter dokumentet i bakgrunnen, se fetch-document.
408, for dokumenter 504 med Retry-After. Ingenting avregnes. Prøv forespørselen igjen litt senere. Mislykkes bare live-hentingen for Sanntid, får du firmaprofilen med de lagrede dataene, uten tillegget for Sanntid.
Nytt forsøk uten dobbel belastning
Avbryter klienten din en forespørsel, kan den likevel bli ferdig hos oss og bli avregnet. Med headeren Idempotency-Key koster det nye forsøket da ingenting.
Velg en egen nøkkel for hver forespørsel og send den uendret med det nye forsøket. En nøkkel har 1 til 128 tegn: bokstaver, sifre, punktum, understrek, kolon og bindestrek, med en bokstav eller et siffer først.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: YOUR_API_KEY" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Tilfelle | Dataendepunkter | Monitoring og webhooks |
|---|---|---|
| Nøkkel påkrevd | nei, valgfri |
ja, ellers 428
|
| Tidsvindu | 24 timer | 24 timer |
| Samme nøkkel, samme parametere | Resultatet igjen, uten avregning | Lagret svar med statusen sin |
| Samme nøkkel, andre parametere |
422 idempotency_key_reused |
409 idempotency_conflict |
| Etter en feil | Nøkkelen forblir ledig | Den samme feilen kommer tilbake, ny nøkkel nødvendig |
Dataendepunkter
fetch-organization, fetch-person, search-organizations og fetch-document godtar nøkkelen som valg. Gjentar du en forespørsel med samme nøkkel og samme parametere innen 24 timer, får du resultatet igjen, uten avregning.
Det første svaret har headeren Idempotency-Status: created, hvert nye forsøk Idempotency-Status: replayed og meta.request_credit_cost: 0. Et nytt forsøk trenger ingen saldo.
Bare et levert resultat binder nøkkelen. Etter en feil kan du derfor fortsette å bruke den samme nøkkelen. Samme nøkkel med andre parametere gir 422 med idempotency_key_reused. Dataendepunktene ignorerer en nøkkel i et annet format, så hold deg nøyaktig til formatet.
signals godtar ingen idempotensnøkkel.
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 og webhooks
Skriveforespørsler til /v1/account/monitors, /v1/account/webhook-endpoints og /v1/account/webhook-deliveries trenger nøkkelen. Uten den svarer API-et med 428; en nøkkel i feil format gir 400.
Innen 24 timer returnerer samme nøkkel med samme parametere det lagrede svaret med statusen sin, pluss Idempotency-Status: replayed. Det gjelder også for feil. For et nytt forsøk, for eksempel en ny verifisering, bruker du derfor en ny nøkkel.
Samme nøkkel med andre parametere gir 409 med idempotency_conflict. Kjører den første forespørselen fortsatt, får du 409 med idempotency_in_progress.
Planlegg nye forsøk
Ikke alle feil er verdt et nytt forsøk. Slik går du frem:
- Prøv igjen:
408,429etterRetry-Afterog5xx. Vent lenger mellom forsøkene hver gang, for eksempel 2, 4 og 8 sekunder, og stopp etter noen forsøk. - Rett først, send deretter på nytt:
400,401,402,403,404og422. Sender du den samme forespørselen igjen, får du det samme resultatet. - Send en idempotensnøkkel med betalte forespørsler. Da koster et nytt forsøk etter et avbrudd ingenting.