Limieten
Hoeveel aanvragen je kunt doen.
Aanvragen per minuut
Elk endpoint staat een vast aantal aanvragen per minuut toe. Voor de data-endpoints en voor het lezen van het account tellen alle sleutels en tokens van een account samen. Elke aanvraag telt, ook een geweigerde.
| Endpoint | Wat | Limiet per minuut |
|---|---|---|
| fetch-organization | Bedrijfsprofiel | 60 |
| fetch-person | Persoonsprofiel | 60 |
| search-organizations | Zoeken & exporteren | 60 |
| fetch-document | Documenten | 5 |
| signals | Signals | 60 |
| account | Het account lezen | 30 |
| account, auth/tokens | Bearer-tokens beheren; sleutels, monitors en webhook-endpoints aanmaken, wijzigen en verwijderen | 10 |
| account/webhook-endpoints | Een webhook-endpoint verifiëren en testen, het secret roteren | 6 |
Zoeken, documenten en Signals delen een quotum van 60 aanvragen per minuut. Documenten hebben daarnaast een eigen, kleinere limiet.
Schrijfaanvragen aan het account, Monitoring en webhooks tellen ook mee voor de accountlimiet. Dezelfde getallen staan onder „Kosten en limieten” op elke endpointpagina.
De limieten zijn in elk creditabonnement gelijk. Heb je meer aanvragen per minuut nodig, dan kan een Enterprise-contract je hogere limieten geven.
Limiet bereikt
Boven de limiet antwoordt de API met 429. De header Retry-After zegt na hoeveel seconden je weer aanvragen kunt sturen. Hetzelfde getal staat in het veld retry_after.
Elk antwoord toont in headers hoeveel ruimte je nog hebt:
| Header | Betekenis | Voorbeeld |
|---|---|---|
| X-RateLimit-Limit | De limiet per minuut van dit endpoint. |
30 |
| X-RateLimit-Remaining | Hoeveel aanvragen er in deze minuut nog mogelijk zijn. |
0 |
| Retry-After |
Alleen bij 429: seconden tot de volgende mogelijke aanvraag.
|
17 |
| X-RateLimit-Reset |
Alleen bij 429: het tijdstip waarop je verder kunt, als Unix-tijd.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Stuur je veel aanvragen, let dan op X-RateLimit-Remaining en rem zelf af voordat de API met 429 antwoordt. Een aanvraag boven de limiet kost niets.
Timeouts
De meeste antwoorden komen binnen een paar seconden. De AI-modus, de feature news, realtime-opvragingen, fetch-person en documenten duren langer, omdat we documenten en realtime-gegevens direct uit het register halen.
Stel de timeout van je client in op minstens 120 seconden, vooral voor Realtime, fetch-person en documenten. Een te korte timeout breekt aanvragen af die bijna klaar zijn.
Voor documenten is er ook async=true: de API antwoordt meteen met 202 en haalt het document op de achtergrond op, zie fetch-document.
408, bij documenten 504 met Retry-After. Er wordt niets berekend. Herhaal de aanvraag wat later. Mislukt alleen de live-opvraging voor Realtime, dan krijg je het bedrijfsprofiel met de opgeslagen gegevens, zonder de Realtime-toeslag.
Opnieuw proberen zonder dubbele afrekening
Breekt je client een aanvraag af, dan kan die bij ons toch nog afronden en worden berekend. Met de header Idempotency-Key kost de herhaling dan niets.
Kies voor elke aanvraag een eigen sleutel en stuur die ongewijzigd mee bij de herhaling. Een sleutel heeft 1 tot 128 tekens: letters, cijfers, punt, underscore, dubbele punt en koppelteken, beginnend met een letter of een cijfer.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: JOUW_API_SLEUTEL" \ -H "Idempotency-Key: hetzner-profiel-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Geval | Data-endpoints | Monitoring en webhooks |
|---|---|---|
| Sleutel verplicht | nee, optioneel |
ja, anders 428
|
| Venster | 24 uur | 24 uur |
| Zelfde sleutel, zelfde parameters | Resultaat opnieuw, zonder afrekening | Opgeslagen antwoord met zijn status |
| Zelfde sleutel, andere parameters |
422 idempotency_key_reused |
409 idempotency_conflict |
| Na een fout | Sleutel blijft vrij | Dezelfde fout komt terug, nieuwe sleutel nodig |
Data-endpoints
fetch-organization, fetch-person, search-organizations en fetch-document accepteren de sleutel als optie. Herhaal je een aanvraag binnen 24 uur met dezelfde sleutel en dezelfde parameters, dan krijg je het resultaat opnieuw, zonder afrekening.
Het eerste antwoord heeft de header Idempotency-Status: created, elke herhaling Idempotency-Status: replayed en meta.request_credit_cost: 0. Een herhaling heeft geen saldo nodig.
Alleen een geleverd resultaat bindt de sleutel. Na een fout kun je dus dezelfde sleutel blijven gebruiken. Dezelfde sleutel met andere parameters geeft 422 met idempotency_key_reused. Een sleutel in een ander formaat negeren de data-endpoints, houd je dus precies aan het formaat.
signals accepteert geen idempotency-sleutel.
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 en webhooks
Schrijfaanvragen aan /v1/account/monitors, /v1/account/webhook-endpoints en /v1/account/webhook-deliveries hebben de sleutel nodig. Zonder sleutel antwoordt de API met 428; een sleutel in het verkeerde formaat geeft 400.
Binnen 24 uur levert dezelfde sleutel met dezelfde parameters het opgeslagen antwoord met zijn status, plus Idempotency-Status: replayed. Dat geldt ook voor fouten. Voor een nieuwe poging, zoals opnieuw verifiëren, gebruik je daarom een nieuwe sleutel.
Dezelfde sleutel met andere parameters geeft 409 met idempotency_conflict. Loopt de eerste aanvraag nog, dan krijg je 409 met idempotency_in_progress.
Herhalingen plannen
Niet elke fout is een tweede poging waard. Zo ga je te werk:
- Opnieuw proberen:
408,429naRetry-Afteren5xx. Wacht elke keer langer tussen de pogingen, bijvoorbeeld 2, 4 en 8 seconden, en stop na een paar pogingen. - Eerst corrigeren, dan opnieuw versturen:
400,401,402,403,404en422. Dezelfde aanvraag nog eens versturen geeft hetzelfde resultaat. - Stuur bij betaalde aanvragen een idempotency-sleutel mee. Dan kost een herhaling na een afgebroken aanvraag niets.