Rate-Limits und Kontingente#

EnConvert misst genau eine Sache: die Operation. Dein Plan kauft eine Anzahl Operationen pro Monat, dazu eine Upload-Obergrenze, ein Aufbewahrungsfenster und eine Batch-Größe. Diese Seite sagt dir, was eine Op ist, was jeder Plan bekommt und welcher Statuscode zurückkommt, wenn du darüber hinausgehst.

Zwei Limits werden leicht verwechselt. Das monatliche Kontingent antwortet mit 402. Der Rate-Limiter für kurze Zeitfenster antwortet mit 429. Das sind getrennte Systeme, und keines ersetzt das andere.

Was als Operation zählt#

Eine Op ist eine Arbeitseinheit. Jeder Endpunkt berechnet dieselbe eine Op für dieselbe eine Einheit, ohne Multiplikatoren und ohne Buckets pro Endpunkt. Auch nach Renderzeit wird nichts abgerechnet: Eine Seite, die 30 Sekunden zum Rendern braucht, kostet exakt so viel wie eine Seite, die zwei Sekunden braucht.

Die Einheit selbst unterscheidet sich je Endpunkt, denn „eine Arbeitseinheit“ bedeutet bei einer einzelnen Datei etwas anderes als bei einem Crawl:

Lookup, Distill, Discover und Watch stehen in privater Beta: heute aufrufbar, aber nicht angekündigt und nicht allgemein verfügbar. Die Zählregeln oben gelten für sie genau so, wie sie dastehen; siehe Demnächst.

Zwei weitere Regeln gelten überall. Ops werden bei Abschluss gezählt, eine fehlgeschlagene Anfrage zehrt also nicht an deinem Kontingent. Und eine Anfrage mit mehreren Einheiten wird vorab geprüft: Ein Batch mit 40 URLs wird gegen dein verbleibendes Kontingent gemessen, bevor die erste URL abgerufen wird, und deshalb komplett abgelehnt statt halb verarbeitet.

Lesende Aufrufe sind kostenlos. Das Pollen eines Jobs, das Auflisten deiner Ingest-Jobs oder Watcher und das Herunterladen eines fertigen Artefakts verbrauchen nichts.

Pläne#

Jede Zahl unten wird von der API durchgesetzt, keine davon ist nur ein Richtwert. Die Slug-Spalte ist das, was du in API-Antworten siehst (zum Beispiel das Feld tier bei einem 413); der Name ist das, was du auf der Preisseite und auf einer Rechnung siehst.

Enterprise-Limits werden pro Vertrag festgelegt, nicht aus dieser Tabelle.

Das Founding-Kontingent ist schnell versehentlich aufgebraucht. 500 Ops sind 500 Seiten, und ein einziger Crawl kann sie in einem Aufruf komplett verbrauchen; setze also max_pages, bevor du Ingest auf eine Dokumentations-Site richtest.

Ops werden zu Beginn jedes Abrechnungszyklus zurückgesetzt und nicht übertragen. Die Upload-Obergrenze wird gegen die exakte Byte-Anzahl des hochgeladenen Teils geprüft, bevor eine Konvertierung startet, und eine Datei, die genau der Obergrenze entspricht, wird akzeptiert. Die Aufbewahrung ist die Dauer, die ein erzeugtes Artefakt im Speicher bleibt; die signierte URL, die darauf zeigt, lebt 15 Minuten und kann über den Status-Endpunkt neu ausgestellt werden, bis das Aufbewahrungsfenster schließt. Das behandelt Signierte URLs.

Kontingente, die keine Ops sind#

Zwei Zuteilungen stehen neben dem Ops-Zähler und greifen nie darauf zu.

Nicht genutzte AI-Credits werden in die nächste Periode übertragen. Wenn sie aufgebraucht sind, schlägt deshalb keine Anfrage fehl: Die Schema-Extraktion fällt auf ihr heuristisches und CSS-basiertes Ergebnis zurück, und der Aufruf gelingt weiterhin. Watcher sind ein Platz, den du hältst, kein Verbrauch; ein untätiger Watcher kostet nichts, ein beschäftigter ebenfalls nicht. Gedeckelt ist, wie viele gleichzeitig existieren.

Wenn das monatliche Kontingent aufgebraucht ist#

Die API antwortet mit 402 Payment Required, nie mit 429, und der Body hat die Standardform {"detail": "..."}.

{
    "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue."
}

Auf diesem Pfad gibt es drei Meldungen:

Wenn der Zähler zum ersten Mal 100 Prozent erreicht, bekommt der Projektinhaber zusätzlich eine E-Mail, höchstens eine alle 24 Stunden.

Overage#

Overage gibt es bei jedem kostenpflichtigen Plan, zu $0.02 pro Op, und es ist standardmäßig aus. Aktiviere es, und Anfragen jenseits deines Kontingents funktionieren weiter, jenseits von 3.000 bei Indie, 15.000 bei Studio und 50.000 bei Production, wobei die zusätzlichen Ops zu diesem Satz berechnet werden. Lässt du es aus, ist das Kontingent ein harter Stopp bis zum nächsten Zyklus, und genau das ist der Sinn: Eine außer Kontrolle geratene Schleife kann dich nicht heimlich Geld kosten. Beim kostenlosen Founding-Plan ist der harte Stopp das einzige Verhalten; Enterprise läuft über den Vertrag.

Wo du gerade stehst#

Dafür gibt es keinen Header. Erfolgreiche Antworten enthalten weder einen Zähler für verbleibende Ops noch irgendwelche Nutzungsfelder; die einzigen Wege, deinen Stand zu kennen, sind also das Dashboard und deine eigene Anfragen-Buchhaltung. Plane den 402 ein, statt auf eine Warnung zu warten.

Anfrage-Rate-Limits#

Unabhängig vom monatlichen Kontingent werden Anfragen zusätzlich über kurze Zeitfenster begrenzt, damit ein Projekt nicht alle anderen verdrängt. Drei Fenster laufen gleichzeitig: pro Minute, pro Stunde und pro Tag. Die Limits skalieren mit deinem Plan.

Exakte Zahlen je Fenster stehen hier nicht. Lies sie stattdessen aus der Antwort ab: Eine Ablehnung nennt dir das Limit, das ausgelöst hat, und wie lange du warten musst, und das ist der Wert, den die API tatsächlich durchsetzt.

Fest steht das Verhalten:

• Limits gelten pro Projekt, nicht pro API-Key; das Rotieren von Keys setzt ein Fenster also nicht zurück.
• Öffentlicher (pk_) und privater (sk_) Traffic nutzen getrennte Buckets, und Traffic mit öffentlichem Key trägt unterhalb des Projektfensters eine zusätzliche Obergrenze pro IP.
• Begrenzt werden nur POST-Anfragen, die Arbeit auslösen: die Konvertierungs-Endpunkte, die V2-Endpunkte und das Ausstellen von Tokens. Jedes GET ist ausgenommen, Status-Polling und Downloads lösen also nichts aus.

Eine Ablehnung ist 429 Too Many Requests:

{
    "detail": "Rate limit exceeded. Please slow down and retry shortly."
}

Sie trägt vier Header:

Sowohl RateLimit-Reset als auch Retry-After sind ganze Sekunden und fallen nie unter 1. Die angegebene Anzahl Sekunden warten und einmal erneut versuchen, das ist die vollständige Recovery-Prozedur.

Limits, die keine 429 sind#

Die meisten Limit-Antworten kommen nicht vom Rate-Limiter. Das sind die, auf die Leute tatsächlich stoßen.

413: Der Upload ist zu groß#

Wird die Upload-Obergrenze deines Plans überschritten, kommt ein 413 mit einem strukturierten Objekt als Wert von detail zurück. Lies body.detail.max_size, nicht body.max_size.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

POST /v2/ingest/files ist die Ausnahme: Es antwortet mit 413 und einem einfachen String, File '{filename}' exceeds the {max_size}-byte limit.

403: Ein Batch- oder V1-Feature, das dein Plan nicht hat#

402: Ein abgeschalteter V2-Endpunkt oder eine andere Obergrenze#

V2-Endpunkt-Gates antworten mit 402 statt 403, und das ist die eine Asymmetrie in diesem Schema, die du dir merken solltest:

503: Der Dienst ist ausgelastet, nicht du#

The conversion service is at capacity. Please retry shortly. (gesendet mit Retry-After: 30) und Server is at capacity. Please retry shortly. (gesendet mit Retry-After: 10) sind Kapazitäts-Gates auf unserer Seite. Sie werden dir nicht angerechnet und sind kein Rate-Limiting. Lies Retry-After, statt anzunehmen, dass eine Wartezeit für beide gilt.

Verwandte Seiten#

• Fehler enthält jeden Statuscode und jede Meldung, die die API zurückgeben kann.
• Batch-Verarbeitung behandelt, wie das Batch-Limit mit ZIP-Ausgabe und Polling zusammenspielt.
• Datei-Ingestion behandelt die Upload-Pfade, für die die Größenobergrenze gilt.
• Signierte URLs behandelt das 15-Minuten-Download-Fenster, das innerhalb deines Aufbewahrungsfensters liegt.