Grænser
Hvor mange forespørgsler du kan sende.
Forespørgsler pr. minut
Hvert endpoint tillader et fast antal forespørgsler pr. minut. For data-endpoints og for at læse kontoen tæller alle en kontos nøgler og tokens sammen. Hver forespørgsel tæller, også en afvist.
| Endpoint | Hvad | Grænse pr. minut |
|---|---|---|
| fetch-organization | Virksomhedsprofil | 60 |
| fetch-person | Personprofil | 60 |
| search-organizations | Søgning & eksport | 60 |
| fetch-document | Dokumenter | 5 |
| signals | Signals | 60 |
| account | Læs kontoen | 30 |
| account, auth/tokens | Administrer bearer-tokens; opret, opdater og slet nøgler, monitors og webhook-endpoints | 10 |
| account/webhook-endpoints | Verificér og test et webhook-endpoint, rotér secret | 6 |
Søgning, dokumenter og Signals deler en kvote på 60 forespørgsler pr. minut. Dokumenter har desuden deres egen, mindre grænse.
Skriveforespørgsler til kontoen, Monitoring og webhooks tæller også med i kontogrænsen. De samme tal står under «Omkostninger og grænser» på hver endpoint-side.
Grænserne er de samme i hvert kreditabonnement. Har du brug for flere forespørgsler pr. minut, kan en Enterprise-aftale give dig højere grænser.
Grænse nået
Over grænsen svarer API’et med 429. Headeren Retry-After fortæller dig, efter hvor mange sekunder du kan sende forespørgsler igen. Det samme tal står i feltet retry_after.
Hvert svar viser i headers, hvor meget plads du har tilbage:
| Header | Betydning | Eksempel |
|---|---|---|
| X-RateLimit-Limit | Dette endpoints grænse pr. minut. |
30 |
| X-RateLimit-Remaining | Hvor mange forespørgsler der er mulige i dette minut. |
0 |
| Retry-After |
Kun ved 429: sekunder til den næste mulige forespørgsel.
|
17 |
| X-RateLimit-Reset |
Kun ved 429: tidspunktet, hvor du kan fortsætte, som Unix-tid.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Sender du mange forespørgsler, så hold øje med X-RateLimit-Remaining, og sæt selv farten ned, før API’et svarer med 429. En forespørgsel over grænsen koster intet.
Timeouts
De fleste svar kommer inden for få sekunder. AI-tilstand, featuren news, realtidsopslag, fetch-person og dokumenter tager længere tid, fordi vi henter dokumenter og realtidsdata direkte fra registret.
Sæt din klients timeout til mindst 120 sekunder, især for Realtid, fetch-person og dokumenter. En for kort timeout afbryder forespørgsler, der lige er ved at blive færdige.
For dokumenter findes også async=true: API’et svarer straks med 202 og henter dokumentet i baggrunden, se fetch-document.
408, for dokumenter 504 med Retry-After. Der afregnes intet. Gentag forespørgslen lidt senere. Fejler kun live-opslaget for Realtid, får du virksomhedsprofilen med de gemte data, uden tillægget for Realtid.
Genforsøg uden dobbelt afregning
Afbryder din klient en forespørgsel, kan den stadig blive færdig hos os og blive afregnet. Med headeren Idempotency-Key koster genforsøget så intet.
Vælg en separat nøgle for hver forespørgsel, og send den uændret med ved genforsøget. En nøgle har 1 til 128 tegn: bogstaver, cifre, punktum, understregning, kolon og bindestreg, startende med et bogstav eller et ciffer.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: DIN_API_NOEGLE" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Tilfælde | Data-endpoints | Monitoring og webhooks |
|---|---|---|
| Nøgle påkrævet | nej, valgfri |
ja, ellers 428
|
| Tidsvindue | 24 timer | 24 timer |
| Samme nøgle, samme parametre | Resultatet igen, uden afregning | Gemt svar med dets status |
| Samme nøgle, andre parametre |
422 idempotency_key_reused |
409 idempotency_conflict |
| Efter en fejl | Nøglen forbliver fri | Den samme fejl kommer igen, ny nøgle nødvendig |
Data-endpoints
fetch-organization, fetch-person, search-organizations og fetch-document accepterer nøglen som option. Gentager du en forespørgsel med samme nøgle og samme parametre inden for 24 timer, får du resultatet igen, uden afregning.
Det første svar har headeren Idempotency-Status: created, hvert genforsøg Idempotency-Status: replayed og meta.request_credit_cost: 0. Et genforsøg kræver ingen saldo.
Kun et leveret resultat binder nøglen. Efter en fejl kan du altså fortsat bruge den samme nøgle. Den samme nøgle med andre parametre giver 422 med idempotency_key_reused. Data-endpoints ignorerer en nøgle i et andet format, så hold dig præcis til formatet.
signals accepterer ingen idempotency-nøgle.
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ørgsler til /v1/account/monitors, /v1/account/webhook-endpoints og /v1/account/webhook-deliveries kræver nøglen. Uden den svarer API’et med 428; en nøgle i forkert format giver 400.
Inden for 24 timer returnerer den samme nøgle med de samme parametre det gemte svar med dets status, plus Idempotency-Status: replayed. Det gælder også fejl. Til et nyt forsøg, f.eks. at verificere igen, bruger du derfor en ny nøgle.
Den samme nøgle med andre parametre giver 409 med idempotency_conflict. Kører den første forespørgsel stadig, får du 409 med idempotency_in_progress.
Planlæg dine genforsøg
Ikke alle fejl er et nyt forsøg værd. Sådan gør du:
- Gentag:
408,429efterRetry-Afterog5xx. Vent længere mellem forsøgene hver gang, f.eks. 2, 4 og 8 sekunder, og stop efter nogle forsøg. - Ret først, send så igen:
400,401,402,403,404og422. Sender du den samme forespørgsel igen, får du det samme resultat. - Send en idempotency-nøgle med betalte forespørgsler. Så koster et genforsøg efter en afbrydelse intet.