Limits und Kontingent

Überblick

Die IDParse API setzt zwei Limits durch:

Limit pro Minute. Es begrenzt, wie viele Anfragen Ihr Konto innerhalb von 60 Sekunden senden kann.
Enthaltene Scans. Ihr Tarif enthält eine feste Zahl an Scans pro Kalendermonat. Die Nutzung wird am 1. jedes Monats (UTC) auf 0 zurückgesetzt.

Beide Limits werden bei jeder Extract-Anfrage geprüft. Eine Anfrage muss beide Prüfungen bestehen.

Limit pro Minute

Das Limit pro Minute ist ein gleitendes Fenster (die API zählt die Anfragen der letzten 60 Sekunden). Es gehört zu Ihrem Konto, alle API-Schlüssel des Kontos teilen es sich also. Anfragen, die den Begrenzer pro Minute erreichen, zählen, auch Quota-Aufrufe und Anfragen, die später fehlschlagen. Anfragen, die früher abgelehnt werden (falscher Schlüssel, Wartung), zählen nicht.

Wenn das Limit erreicht ist, antwortet die API mit 429 und dem Fehlercode rate_limited. Ihr Limit pro Minute hängt von Ihrem Tarif ab. Der Header X-RateLimit-Limit zeigt es an.

Enthaltene Scans

Nur ein validierter Erfolg ("success": true) verbraucht einen Ihrer enthaltenen Scans. Siehe Was berechnet wird.

Standardmäßig macht die API einen harten Stopp: Wenn alle enthaltenen Scans des Monats verbraucht sind, erhält jede weitere Extract-Anfrage 429 mit dem Fehlercode quota_exhausted, bis der nächste Monat beginnt. Es können keine zusätzlichen Kosten entstehen.

Der Quota-Endpunkt zeigt das für Ihr Konto geltende Limit als effective_limit. Bei den meisten Konten entspricht es den enthaltenen Scans.

Antwort-Header

Nutzungs-Header in Antworten von POST /v1/extract:

Header	Beschreibung
`X-IDParse-Scans-Included`	Die Scans, die pro Monat in Ihrem Tarif enthalten sind
`X-IDParse-Scans-Used`	Die Scans, die im laufenden Monat verbraucht sind, einschließlich der Berechnung dieser Anfrage
`X-IDParse-Scans-Remaining`	Die enthaltenen Scans, die noch übrig sind, nie unter 0
`X-IDParse-Period-Ends`	Das Ende des laufenden Zeitraums im Format ISO 8601, UTC. Es ist der erste Tag des nächsten Kalendermonats, zum Beispiel `2026-10-01T00:00:00Z`. Der Header entfällt während des kostenlosen Tests, weil dessen Scans nie neu beginnen
`Cache-Control`	`no-store`, damit kein Cache die Antwort aufbewahrt

Wichtig

Die Nutzungs-Header sind eine Momentaufnahme. Die Zahlen werden erfasst, wenn die Anfrage zugelassen wird, und dann um die Berechnung dieser Anfrage korrigiert. Anfragen, die parallel laufen, können in den Zahlen enthalten sein. Cache-Control: no-store ist in jeder Antwort vorhanden, die die Schlüsselprüfung und die Wartungsprüfung bestanden hat. Die vier Nutzungs-Header sind nur vorhanden, wenn die Prüfung der monatlichen Nutzung ein Ergebnis geliefert hat. Sie können fehlen bei frühen Ablehnungen (401, 403, 503 Wartung), bei 429 rate_limited, bei 503 service_unavailable, wenn die Nutzungsprüfung selbst fehlgeschlagen ist, und bei Konten ohne monatliches Limit. Bauen Sie keine Logik, die diese Header in jeder Antwort braucht. GET /v1/quota gibt den aktuellen Nutzungszähler jederzeit zurück. Der Nutzungszähler kann Scans enthalten, die noch verarbeitet werden. Er kann nicht bestätigen, ob eine einzelne unterbrochene Anfrage berechnet wurde.

Weitere Header:

Header	Beschreibung
`X-Request-ID`	Eine eindeutige Kennung der Anfrage, in jeder Antwort. Verwenden Sie sie, um eine Anfrage in Ihren eigenen Protokollen wiederzufinden
`X-RateLimit-Limit`	Die Zahl der Anfragen, die Ihr Konto pro Minute senden kann
`X-RateLimit-Remaining`	Die Anfragen, die im laufenden 60-Sekunden-Fenster noch übrig sind
`X-RateLimit-Reset`	Unix-Zeitstempel des Moments, in dem das laufende Fenster endet
`Retry-After`	In `429`-Antworten und `503`-Antworten: die Zahl der Sekunden, die Sie vor einem neuen Versuch warten sollten

Hinweis

Die X-RateLimit-*-Header beschreiben das Limit pro Minute. Es gibt eine Ausnahme: In einer Antwort 429 quota_exhausted beschreiben sie das monatliche Limit, und X-RateLimit-Reset ist der Beginn des nächsten Monats.

Überschreitung der Limits

Wenn das Limit pro Minute erreicht ist, gibt die API eine Antwort 429 Too Many Requests zurück. Retry-After enthält die Sekunden, bis das Fenster wieder Platz hat.

json

{
    "success": false,
    "error": {
        "type": "https://idparse.com/errors/rate-limited",
        "code": "rate_limited",
        "title": "Rate Limit Exceeded",
        "status": 429,
        "detail": "You have exceeded your plan's per-minute request limit."
    }
}

Wenn alle enthaltenen Scans verbraucht sind, gibt die API ebenfalls 429 zurück, aber mit einem anderen Code. Retry-After enthält die Sekunden, bis der nächste Kalendermonat beginnt.

json

{
    "success": false,
    "error": {
        "type": "https://idparse.com/errors/quota-exhausted",
        "code": "quota_exhausted",
        "title": "Monthly Quota Exhausted",
        "status": 429,
        "detail": "You have used all requests included in your plan for this month."
    }
}

Beide Antworten sind kostenlos. Lesen Sie error.code, um sie zu unterscheiden.

Tipps:

Senden Sie gleich beim ersten Mal ein gutes Bild. Ein nicht lesbares Dokument ist kostenlos, zählt aber trotzdem zum Limit pro Minute.
Speichern Sie das Ergebnis eines Erfolgs auf Ihrer Seite. Senden Sie dieselbe Datei nicht erneut, denn jeder Erfolg wird berechnet.
Verteilen Sie große Stapel über die Zeit, statt alle Dateien auf einmal zu senden.
Überwachen Sie Ihre Nutzung mit dem Quota-Endpunkt oder dem Dashboard.
Wechseln Sie für mehr enthaltene Scans in einen höheren Tarif: Preise.

Quota-Endpunkt

GET /v1/quota gibt Ihren Tarif, Ihre enthaltenen Scans und Ihre Nutzung zurück. Der Endpunkt ist kostenlos, er zählt nie als Scan, und er bleibt erreichbar, nachdem Ihre enthaltenen Scans verbraucht sind. Er zählt trotzdem zum Limit pro Minute.

bash

curl -s "https://api.idparse.com/v1/quota" \
  -H "Authorization: Bearer YOUR_API_KEY"

Die vollständige Antwort ist unter Endpunkte beschrieben.