Rajat – Dokumentaatio | handelsregister.ai

Pyynnöt minuutissa

Jokainen päätepiste sallii kiinteän määrän pyyntöjä minuutissa. Datapäätepisteissä ja tilin lukemisessa kaikki tilin avaimet ja tokenit lasketaan yhteen. Jokainen pyyntö lasketaan, myös hylätty.

Päätepiste
Päätepiste	Mitä	Raja minuutissa
fetch-organization	Yritysprofiili	60
fetch-person	Henkilöprofiili	60
search-organizations	Haku & vienti	60
fetch-document	Asiakirjat	5
signals	Signals	60
account	Tilin lukeminen	30
account, auth/tokens	Bearer-tokenien hallinta; avainten, monitorien ja webhook-päätepisteiden luonti, muutos ja poisto	10
account/webhook-endpoints	Webhook-päätepisteen vahvistus ja testaus, secretin vaihto	6

Haulla, asiakirjoilla ja Signalsilla on yhteinen kiintiö, 60 pyyntöä minuutissa. Asiakirjoilla on lisäksi oma, pienempi rajansa.

Kirjoituspyynnöt tiliin, Monitoringiin ja webhookeihin lasketaan myös tilin rajaan. Samat luvut on lueteltu kohdassa ”Kustannukset ja rajat” jokaisen päätepisteen sivulla.

Rajat ovat samat jokaisessa krediittitilauksessa. Jos tarvitset enemmän pyyntöjä minuutissa, Enterprise-sopimus voi antaa sinulle korkeammat rajat.

Raja saavutettu

Rajan ylittyessä API vastaa 429. Header Retry-After kertoo, monenko sekunnin kuluttua voit taas lähettää pyyntöjä. Sama luku on kentässä retry_after.

Jokainen vastaus näyttää headereissa, paljonko liikkumavaraa sinulla on jäljellä:

Header
Header	Merkitys	Esimerkki
X-RateLimit-Limit	Tämän päätepisteen raja minuutissa.	`30`
X-RateLimit-Remaining	Kuinka monta pyyntöä tällä minuutilla on vielä mahdollista.	`0`
Retry-After	Vain vastauksessa `429`: sekunnit seuraavaan mahdolliseen pyyntöön.	`17`
X-RateLimit-Reset	Vain vastauksessa `429`: hetki, jolloin voit jatkaa, Unix-aikana.	`1793519682`

1{2  "error": "Too many requests",3  "message": "Rate limit exceeded. Retry after 17 seconds.",4  "retry_after": 175}

429 · Esimerkkivastaus rajan ylittyessä

Kun lähetät paljon pyyntöjä, seuraa headeria X-RateLimit-Remaining ja hidasta itse ennen kuin API vastaa 429. Rajan ylittävä pyyntö ei maksa mitään.

Aikakatkaisut

Useimmat vastaukset tulevat muutamassa sekunnissa. AI-tila, ominaisuus news, reaaliaikahaut, fetch-person ja asiakirjat kestävät kauemmin, koska haemme asiakirjat ja reaaliaikadatan suoraan rekisteristä.

Aseta asiakasohjelmasi aikakatkaisuksi vähintään 120 sekuntia, erityisesti Reaaliajalle, fetch-personille ja asiakirjoille. Liian lyhyt aikakatkaisu keskeyttää pyynnöt, jotka ovat juuri valmistumassa.

Asiakirjoille on lisäksi async=true: API vastaa heti 202 ja hakee asiakirjan taustalla, katso fetch-document.

Jos tietolähde ei vastaa ajoissa, saat vastauksen 408, asiakirjoilla 504 ja headerin Retry-After. Mitään ei veloiteta. Toista pyyntö hieman myöhemmin. Jos vain Reaaliajan suora haku epäonnistuu, saat yritysprofiilin tallennetuilla tiedoilla ilman Reaaliajan lisämaksua.

Uudelleenyritys ilman kaksoisveloitusta

Jos asiakasohjelmasi keskeyttää pyynnön, se voi silti valmistua meidän päässämme ja tulla veloitetuksi. Headerilla Idempotency-Key uudelleenyritys ei silloin maksa mitään.

Valitse jokaiselle pyynnölle oma avain ja lähetä se muuttamattomana uudelleenyrityksen mukana. Avaimessa on 1–128 merkkiä: kirjaimia, numeroita, piste, alaviiva, kaksoispiste ja yhdysmerkki, alkaen kirjaimella tai numerolla.

Pyyntö idempotenssiavaimella

curl -G "https://handelsregister.ai/api/v1/fetch-organization" \
  -H "x-api-key: SINUN_API_AVAIMESI" \
  -H "Idempotency-Key: hetzner-profiili-2026-11-01" \
  --data-urlencode "q=Ansbach HRB 6089"

Tapaus
Tapaus	Datapäätepisteet	Monitoring ja webhookit
Avain pakollinen	ei, valinnainen	kyllä, muuten `428`
Aikaikkuna	24 tuntia	24 tuntia
Sama avain, samat parametrit	Tulos uudelleen ilman veloitusta	Tallennettu vastaus tiloineen
Sama avain, eri parametrit	`422` idempotency_key_reused	`409` idempotency_conflict
Virheen jälkeen	Avain pysyy vapaana	Sama virhe palaa, uusi avain tarvitaan

Datapäätepisteet

fetch-organization, fetch-person, search-organizations ja fetch-document hyväksyvät avaimen valinnaisena. Jos toistat pyynnön samalla avaimella ja samoilla parametreilla 24 tunnin sisällä, saat tuloksen uudelleen ilman veloitusta.

Ensimmäisessä vastauksessa on header Idempotency-Status: created, jokaisessa uudelleenyrityksessä Idempotency-Status: replayed ja meta.request_credit_cost: 0. Uudelleenyritys ei vaadi saldoa.

Vain toimitettu tulos sitoo avaimen. Virheen jälkeen voit siis käyttää samaa avainta edelleen. Sama avain eri parametreilla antaa vastauksen 422 ja koodin idempotency_key_reused. Datapäätepisteet ohittavat eri muotoisen avaimen, joten noudata muotoa tarkasti. signals ei hyväksy idempotenssiavainta.

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}

422 · Esimerkkivastaus: sama avain eri parametreilla

Monitoring ja webhookit

Kirjoituspyynnöt polkuihin /v1/account/monitors, /v1/account/webhook-endpoints ja /v1/account/webhook-deliveries vaativat avaimen. Ilman sitä API vastaa 428; väärän muotoinen avain antaa vastauksen 400.

24 tunnin sisällä sama avain samoilla parametreilla palauttaa tallennetun vastauksen tiloineen sekä headerin Idempotency-Status: replayed. Tämä koskee myös virheitä. Uuteen yritykseen, kuten uuteen vahvistukseen, käytät siksi uutta avainta.

Sama avain eri parametreilla antaa vastauksen 409 ja koodin idempotency_conflict. Jos ensimmäinen pyyntö on vielä käynnissä, saat vastauksen 409 ja koodin idempotency_in_progress.

Suunnittele uudelleenyritykset

Kaikki virheet eivät ansaitse toista yritystä. Näin toimit:

Yritä uudelleen: 408, 429 ajan Retry-After jälkeen ja 5xx. Odota yritysten välillä joka kerta pidempään, esimerkiksi 2, 4 ja 8 sekuntia, ja lopeta muutaman yrityksen jälkeen.
Korjaa ensin, lähetä sitten uudelleen: 400, 401, 402, 403, 404 ja 422. Saman pyynnön lähettäminen uudelleen tuo saman tuloksen.
Lähetä maksullisten pyyntöjen mukana idempotenssiavain. Silloin uudelleenyritys keskeytyksen jälkeen ei maksa mitään.