Limits
Wie viele Anfragen du stellen kannst.
Anfragen pro Minute
Jeder Endpunkt erlaubt eine feste Zahl an Anfragen pro Minute. Bei den Daten-Endpunkten und beim Lesen des Kontos zählen alle Schlüssel und Tokens eines Kontos zusammen. Jede Anfrage zählt, auch eine abgelehnte.
| Endpunkt | Was | Limit pro Minute |
|---|---|---|
| fetch-organization | Firmenprofil | 60 |
| fetch-person | Personenprofil | 60 |
| search-organizations | Suche & Export | 60 |
| fetch-document | Dokumente | 5 |
| signals | Signals | 60 |
| account | Konto lesen | 30 |
| account, auth/tokens | Bearer-Tokens verwalten; Schlüssel, Monitore und Webhook-Endpoints anlegen, ändern und löschen | 10 |
| account/webhook-endpoints | Webhook-Endpoint verifizieren, testen, Secret rotieren | 6 |
Suche, Dokumente und Signals teilen sich ein Kontingent von 60 Anfragen pro Minute. Für Dokumente gilt zusätzlich ihr eigenes, kleineres Limit.
Schreibende Anfragen an Konto, Monitoring und Webhooks zählen außerdem zum Limit für das Konto. Dieselben Zahlen stehen unter „Kosten und Limits“ auf jeder Endpunktseite.
Die Limits sind in jedem Credit-Abo gleich. Brauchst du mehr Anfragen pro Minute, sind mit einem Enterprise-Vertrag höhere Limits möglich.
Limit erreicht
Über dem Limit antwortet die API mit 429. Der Header Retry-After sagt, nach wie vielen Sekunden du wieder anfragen kannst. Dieselbe Zahl steht im Feld retry_after.
Jede Antwort zeigt in Headern, wie viel Spielraum bleibt:
| Header | Bedeutung | Beispiel |
|---|---|---|
| X-RateLimit-Limit | Das Limit dieses Endpunkts pro Minute. |
30 |
| X-RateLimit-Remaining | Wie viele Anfragen in dieser Minute noch möglich sind. |
0 |
| Retry-After |
Nur bei 429: Sekunden bis zur nächsten möglichen Anfrage.
|
17 |
| X-RateLimit-Reset |
Nur bei 429: der Zeitpunkt, ab dem es weitergeht, als Unix-Zeit.
|
1793519682 |
1{2 "error": "Too many requests",3 "message": "Rate limit exceeded. Retry after 17 seconds.",4 "retry_after": 175}
Bei vielen Anfragen behältst du X-RateLimit-Remaining im Blick und bremst selbst, bevor die API mit 429 antwortet. Eine Anfrage über dem Limit kostet nichts.
Zeitüberschreitungen
Die meisten Antworten kommen in wenigen Sekunden. Länger dauern der AI-Mode, das Feature news, Echtzeit-Abrufe, fetch-person und Dokumente. Denn Dokumente und Echtzeit-Daten holen wir direkt aus dem Register.
Stell den Timeout deines Clients auf mindestens 120 Sekunden, besonders für Echtzeit, fetch-person und Dokumente. Ein zu kurzer Timeout bricht Anfragen ab, die gerade fertig werden.
Für Dokumente gibt es zusätzlich async=true: Die API antwortet sofort mit 202 und holt das Dokument im Hintergrund, siehe fetch-document.
408, bei Dokumenten 504 mit Retry-After. Berechnet wird nichts. Wiederhole die Anfrage etwas später. Gelingt nur der Live-Abruf bei Echtzeit nicht, kommt das Firmenprofil mit den gespeicherten Daten, ohne Aufschlag für Echtzeit.
Wiederholen ohne Doppelabrechnung
Bricht dein Client eine Anfrage ab, kann sie bei uns trotzdem fertig laufen und berechnet werden. Mit dem Header Idempotency-Key kostet die Wiederholung dann nichts.
Wähle für jede Anfrage einen eigenen Key und schick ihn bei der Wiederholung unverändert mit. Ein Key hat 1 bis 128 Zeichen: Buchstaben, Ziffern, Punkt, Unterstrich, Doppelpunkt und Bindestrich, am Anfang ein Buchstabe oder eine Ziffer.
curl -G "https://handelsregister.ai/api/v1/fetch-organization" \ -H "x-api-key: DEIN_API_SCHLUESSEL" \ -H "Idempotency-Key: hetzner-profil-2026-11-01" \ --data-urlencode "q=Ansbach HRB 6089"
| Fall | Daten-Endpunkte | Monitoring und Webhooks |
|---|---|---|
| Key nötig | nein, optional |
ja, sonst 428
|
| Zeitraum | 24 Stunden | 24 Stunden |
| Gleicher Key, gleiche Parameter | Ergebnis erneut, ohne Berechnung | Gespeicherte Antwort mit ihrem Status |
| Gleicher Key, andere Parameter |
422 idempotency_key_reused |
409 idempotency_conflict |
| Nach einem Fehler | Key bleibt frei | Derselbe Fehler kommt erneut, neuer Key nötig |
Daten-Endpunkte
fetch-organization, fetch-person, search-organizations und fetch-document nehmen den Key optional an. Wiederholst du eine Anfrage mit demselben Key und denselben Parametern innerhalb von 24 Stunden, bekommst du das Ergebnis erneut, ohne Berechnung.
Die erste Antwort trägt den Header Idempotency-Status: created, jede Wiederholung Idempotency-Status: replayed und meta.request_credit_cost: 0. Eine Wiederholung braucht kein Guthaben.
Erst ein geliefertes Ergebnis bindet den Key. Nach einem Fehler kannst du denselben Key also weiter nutzen. Derselbe Key mit anderen Parametern ergibt 422 mit idempotency_key_reused. Einen Key in anderem Format beachten die Daten-Endpunkte nicht. Halte dich deshalb genau an das Format.
signals nimmt keinen Idempotency-Key an.
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 und Webhooks
Schreibende Anfragen an /v1/account/monitors, /v1/account/webhook-endpoints und /v1/account/webhook-deliveries brauchen den Key. Ohne ihn antwortet die API mit 428, ein Key im falschen Format ergibt 400.
Innerhalb von 24 Stunden liefert derselbe Key mit denselben Parametern die gespeicherte Antwort mit ihrem Status, dazu Idempotency-Status: replayed. Das gilt auch für Fehler. Für einen neuen Versuch, etwa ein erneutes Verifizieren, nimmst du deshalb einen neuen Key.
Derselbe Key mit anderen Parametern ergibt 409 mit idempotency_conflict. Läuft die erste Anfrage noch, kommt 409 mit idempotency_in_progress.
Wiederholungen planen
Nicht jeder Fehler lohnt einen zweiten Versuch. So gehst du vor:
- Wiederholen:
408,429nachRetry-Afterund5xx. Warte zwischen den Versuchen immer länger, etwa 2, 4 und 8 Sekunden, und hör nach einigen Versuchen auf. - Erst korrigieren, dann neu senden:
400,401,402,403,404und422. Dieselbe Anfrage bringt hier dasselbe Ergebnis. - Schick bei kostenpflichtigen Anfragen einen Idempotency-Key mit. Dann kostet eine Wiederholung nach einem Abbruch nichts.