Fehler
Wie Fehler aussehen und was du tun kannst.
Aufbau einer Fehlerantwort
Ob eine Anfrage geklappt hat, zeigt immer der HTTP-Status: 2xx heißt Erfolg, alles ab 400 ist ein Fehler. Werte in deinem Code zuerst den Status aus. Wie der Inhalt der Antwort aussieht, hängt vom Endpunkt und vom Fehler ab.
| Form | Wo sie vorkommt | Felder |
|---|---|---|
| Fehlercode mit meta |
fetch-organization, fetch-person, search-organizations, fetch-document und /v1/account, wenn sie eine Anfrage ablehnen
|
error (Code oder kurzer Text), teils auch message; in meta die Erklärung message sowie request_credit_cost und credits_remaining
|
| Liste in detail |
Keine passende Firma oder Person gefunden (404), ungültige Suchfilter (422)
|
detail mit je type (etwa not_found), loc, msg und input; dazu meta
|
Problem Details (application/problem+json)
|
Alle Fehler von signals |
type, title, status, code, detail, bei ungültigen Parametern invalid_params; in meta auch request_id
|
| Nur error |
Anmeldung (401, 403 bei unbestätigter E-Mail-Adresse) und Limits (429)
|
error; beim Limit auch message und retry_after
|
| Nur meta |
Zu wenig Credits (402), außer bei signals
|
meta.message, meta.request_credit_cost (der nötige Betrag) und meta.credits_remaining
|
Entscheide in deinem Code anhand des Status und der festen Codes in error bzw. code. Die Texte in message, msg und detail sind auf Englisch und für Menschen gedacht. Schreib sie in dein Log.
Schick den Header Accept: application/json mit. Dann antwortet die API auch bei einem unbekannten Pfad oder einer falschen Methode mit JSON.
1{2 "error": "validation_failed",3 "meta": {4 "message": "financial_statement_type must be one of: auto, annual, consolidated.",5 "request_credit_cost": 0,6 "credits_remaining": 1457 }8}
1{2 "detail": [3 {4 "type": "not_found",5 "loc": [6 "query",7 "person_q"8 ],9 "msg": "Could not verify with sufficient confidence that 'Erika Musterfrau-Nichtvorhanden' is affiliated with 'Hetzner Online GmbH'",10 "input": {11 "person_q": "Erika Musterfrau-Nichtvorhanden",12 "organization_q": "Hetzner Online GmbH"13 }14 }15 ],16 "meta": {17 "request_credit_cost": 0,18 "credits_remaining": 14519 }20}
1{2 "type": "https://handelsregister.ai/problems/invalid-request",3 "title": "Invalid request",4 "status": 422,5 "code": "INVALID_REQUEST",6 "detail": "One or more Signals parameters are invalid.",7 "invalid_params": {8 "limit": [9 "Unknown Signals parameter."10 ]11 },12 "meta": {13 "request_id": "req_01m6b25551xazxjpc5ny6b2cx0",14 "request_credit_cost": 0,15 "credits_remaining": 14516 }17}
Statuscodes
Die Tabelle zeigt jeden Fehlerstatus der API, was ihn auslöst und was du tun kannst. Welche davon ein Endpunkt liefert, steht auf seiner Seite.
| Status | Ursache | Was du tun kannst |
|---|---|---|
| 400 |
Ein Parameter ist ungültig, etwa eine falsche company_id oder ein zu kurzer Suchbegriff. Auch api_key in der URL bei /v1/account/*. |
Die Anfrage nach meta.message korrigieren. |
| 401 | Kein gültiger API-Schlüssel und kein gültiges Token. |
Schlüssel im Header x-api-key mitschicken, siehe Authentifizierung. |
| 402 | Dein Guthaben deckt nicht die höchstmöglichen Kosten der Anfrage. | Credits aufladen oder weniger Features anfragen, siehe Abrechnung. |
| 403 | E-Mail-Adresse nicht bestätigt, Plan nötig (etwa für fetch-person, Suchfilter ab Pro oder einzelne Signals-Themen) oder fehlende Berechtigung des Tokens. | E-Mail bestätigen, Credit-Abo wählen oder ein Token mit der passenden Berechtigung nutzen. |
| 404 | Keine passende Firma, Person oder kein solches Dokument. Bei Konto-Endpunkten eine unbekannte ID. |
Registergericht mit Registernummer oder die entity_id nutzen. |
| 408 | Die Anfrage hat zu lange gedauert, etwa weil das Register bei einem Echtzeit-Abruf langsam antwortet. | Später wiederholen. Es wurde nichts berechnet. |
| 409 | Monitoring und Webhooks: der Idempotency-Key gehört zu anderen Parametern oder läuft noch, oder es gibt schon einen Monitor für diese Firma. | Neuen Key nehmen, kurz warten oder den vorhandenen Monitor nutzen. |
| 415 | Das Dokument liegt im Register nur als TIFF-Bild vor. Die API liefert Dokumente als PDF oder XML. | Das Dokument direkt im Registerportal abrufen. Es wurde nichts berechnet. |
| 422 |
Ein Wert ist ungültig, etwa financial_years außerhalb des erlaubten Bereichs. Auch ein Idempotency-Key, der schon zu anderen Parametern gehört. |
Wert nach meta.message oder invalid_params korrigieren, für neue Parameter einen neuen Key nehmen. |
| 428 | Eine schreibende Anfrage an Monitoring oder Webhooks ohne Idempotency-Key. |
Den Header Idempotency-Key mitschicken. |
| 429 | Zu viele Anfragen in einer Minute. |
So viele Sekunden warten, wie Retry-After angibt, siehe Limits. |
| 500 | Ein vorübergehender Fehler, etwa weil die Datenquelle kurz nicht erreichbar war oder das Register einen Fehler geliefert hat. | Mit wachsendem Abstand wiederholen. |
| 502 | Die Suche oder das Register hat eine unlesbare Antwort geliefert. | Mit wachsendem Abstand wiederholen. Es wurde nichts berechnet. |
| 503 |
Ein Dienst ist vorübergehend nicht verfügbar: Signals, Monitoring, das Prüfen von Webhooks oder ein Dokumentabruf mit async=true. |
Nach Retry-After oder etwas später wiederholen. |
| 504 | fetch-document: Das Register hat nicht rechtzeitig geantwortet. |
Nach Retry-After erneut anfragen. Es wurde nichts berechnet. |
504 und zahlst nichts. Gelingt ein Echtzeit-Abruf nicht, liefert fetch-organization die gespeicherten Daten, ohne Aufschlag für Echtzeit. Dauert eine Anfrage zu lange, kommt 408, ebenfalls ohne Kosten. Wiederhole die Anfrage einige Minuten später.
Kostenlose Anfragen
Eine abgelehnte oder gescheiterte Anfrage kostet nichts. Du erkennst das an meta.request_credit_cost: 0, bei Signals auch am Header X-Credits-Charged: 0.
Kostenlos sind insbesondere:
- Anfragen ohne gültigen Zugang (
401,403) und über dem Limit (429) - Anfragen mit ungültigen Parametern (
400,422) und bei zu wenig Credits (402) - Anfragen, die keine Firma, Person oder kein Dokument finden (
404), außer mit AI-Mode - Zeitüberschreitungen (
408, bei Dokumenten504) und Störungen der Datenquelle (5xx)
Eine Ausnahme ist der AI-Mode: Er wird berechnet, sobald die Recherche gelaufen ist, auch wenn sie keine Firma findet oder die Datenquelle einen Fehler meldet. Nur wenn die API die Anfrage mit 408 abbricht, entfällt auch er.
Umgekehrt gilt: Eine erfolgreiche Suche ohne Treffer und eine leere Seite Signals werden berechnet. Features ohne Daten kosten dagegen nie etwas, siehe Abrechnung. Für die Aufschläge AI-Mode und Echtzeit gelten eigene Regeln, siehe Aufschläge.