Gränser
Hur många förfrågningar du kan göra.
Förfrågningar per minut
Varje endpoint tillåter ett fast antal förfrågningar per minut. För data-endpoints och för att läsa kontot räknas alla nycklar och tokens för ett konto tillsammans. Varje förfrågan räknas, även en avvisad.
| Endpoint | Vad | Gräns per minut |
|---|---|---|
| fetch-organization | Företagsprofil | 60 |
| fetch-person | Personprofil | 60 |
| search-organizations | Sök & export | 60 |
| fetch-document | Dokument | 5 |
| signals | Signals | 60 |
| account | Läsa kontot | 30 |
| account, auth/tokens | Hantera bearer-tokens; skapa, ändra och radera nycklar, bevakningar och webhook-endpoints | 10 |
| account/webhook-endpoints | Verifiera och testa en webhook-endpoint, rotera secret | 6 |
Sökning, dokument och Signals delar en kvot på 60 förfrågningar per minut. Dokument har dessutom en egen, mindre gräns.
Skrivande förfrågningar till kontot, Bevakning och webhooks räknas också mot kontots gräns. Samma siffror står under ”Kostnader och gränser” på varje endpoint-sida.
Gränserna är desamma i varje kreditprenumeration. Om du behöver fler förfrågningar per minut kan ett Enterprise-avtal ge dig högre gränser.
Gränsen nådd
Över gränsen svarar API:et med 429. Headern Retry-After anger efter hur många sekunder du kan skicka förfrågningar igen. Samma siffra står i fältet retry_after.
Varje svar visar i headers hur mycket utrymme du har kvar:
| Header | Betydelse | Exempel |
|---|---|---|
| X-RateLimit-Limit | Denna endpoints gräns per minut. |
30 |
| X-RateLimit-Remaining | Hur många fler förfrågningar som är möjliga denna minut. |
0 |
| Retry-After |
Bara vid 429: sekunder till nästa möjliga förfrågan.
|
17 |
| X-RateLimit-Reset |
Bara vid 429: tidpunkten då du kan fortsätta, 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 skickar många förfrågningar håller du koll på X-RateLimit-Remaining och saktar själv ned innan API:et svarar med 429. En förfrågan över gränsen kostar ingenting.
Timeouts
De flesta svar kommer inom några sekunder. AI-läget, funktionen news, realtidshämtningar, fetch-person och dokument tar längre tid, eftersom vi hämtar dokument och realtidsdata direkt från registret.
Ställ in din klients timeout på minst 120 sekunder, särskilt för Realtid, fetch-person och dokument. En för kort timeout avbryter förfrågningar som precis håller på att bli klara.
För dokument finns dessutom async=true: API:et svarar direkt med 202 och hämtar dokumentet i bakgrunden, se fetch-document.
408, för dokument 504 med Retry-After. Ingenting debiteras. Upprepa förfrågan lite senare. Om bara live-hämtningen för Realtid misslyckas får du företagsprofilen med sparade data, utan tillägget för Realtid.
Nytt försök utan dubbeldebitering
Om din klient avbryter en förfrågan kan den ändå slutföras hos oss och debiteras. Med headern Idempotency-Key kostar det nya försöket då ingenting.
Välj en egen nyckel för varje förfrågan och skicka den oförändrad med det nya försöket. En nyckel har 1 till 128 tecken: bokstäver, siffror, punkt, understreck, kolon och bindestreck, med början på en bokstav eller siffra.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: DIN_API_NYCKEL" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Fall | Data-endpoints | Bevakning och webhooks |
|---|---|---|
| Nyckel krävs | nej, valfri |
ja, annars 428
|
| Tidsfönster | 24 timmar | 24 timmar |
| Samma nyckel, samma parametrar | Resultatet igen, utan debitering | Sparat svar med dess status |
| Samma nyckel, andra parametrar |
422 idempotency_key_reused |
409 idempotency_conflict |
| Efter ett fel | Nyckeln förblir ledig | Samma fel kommer tillbaka, ny nyckel behövs |
Data-endpoints
fetch-organization, fetch-person, search-organizations och fetch-document tar emot nyckeln som tillval. Om du upprepar en förfrågan med samma nyckel och samma parametrar inom 24 timmar får du resultatet igen, utan debitering.
Det första svaret har headern Idempotency-Status: created, varje upprepning Idempotency-Status: replayed och meta.request_credit_cost: 0. En upprepning kräver inget saldo.
Bara ett levererat resultat binder nyckeln. Efter ett fel kan du alltså fortsätta använda samma nyckel. Samma nyckel med andra parametrar ger 422 med idempotency_key_reused. Data-endpoints ignorerar en nyckel i ett annat format, så håll dig exakt till formatet.
signals tar inte emot någon idempotency-nyckel.
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}
Bevakning och webhooks
Skrivande förfrågningar till /v1/account/monitors, /v1/account/webhook-endpoints och /v1/account/webhook-deliveries kräver nyckeln. Utan den svarar API:et med 428; en nyckel i fel format ger 400.
Inom 24 timmar returnerar samma nyckel med samma parametrar det sparade svaret med dess status, plus Idempotency-Status: replayed. Det gäller även för fel. För ett nytt försök, som att verifiera igen, använder du därför en ny nyckel.
Samma nyckel med andra parametrar ger 409 med idempotency_conflict. Om den första förfrågan fortfarande körs får du 409 med idempotency_in_progress.
Planera dina nya försök
Inte varje fel är värt ett andra försök. Så här går du till väga:
- Försök igen:
408,429efterRetry-Afteroch5xx. Vänta längre mellan försöken varje gång, till exempel 2, 4 och 8 sekunder, och sluta efter några försök. - Rätta först, skicka sedan igen:
400,401,402,403,404och422. Samma förfrågan igen ger samma resultat. - Skicka en idempotency-nyckel med avgiftsbelagda förfrågningar. Då kostar ett nytt försök efter ett avbrott ingenting.