--- seo_title: Rate-Limits, Ops-Kontingente und Plan-Limits | EnConvert meta_desc: Monatliche Ops-Kontingente je Plan, Upload-Obergrenzen, Artefakt-Aufbewahrung und Rate-Limits, dazu genau die Antwort der API, wenn du ein Limit überschreitest. keywords: api rate limits, monatliches ops kontingent api, was zählt als operation api, 402 payment required kontingent erreicht, 429 rate limit header api, retry-after header api, maximale dateigröße pro plan api, batch größenlimit api --- # 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: | Endpunkt | Was eine Op abdeckt | |----------|------------------| | [`POST /v1/convert/*`](/de/docs/endpoints/convert.md) | Eine Konvertierung. Ein Datei-Upload ist eine Op. Ein URL-Batch mit 20 URLs sind 20 Ops. | | [`POST /v2/perceive`](/de/docs/endpoints/perceive.md) | Ein URL-Abruf. Ein Batch mit 20 URLs sind 20 Ops. Ein Cache-Hit wird wie jeder andere Abruf berechnet. | | [`POST /v2/ingest`](/de/docs/endpoints/ingest.md) | Eine abgeschlossene Seite. Seiten, die beim Rendern und Chunken fehlschlagen, werden nicht gezählt. | | [`POST /v2/lookup`](/de/docs/coming-soon/lookup.md) | Eine Query, plus eine Op für jedes Ergebnis, das die API für dich rendert. Die beiden Kosten summieren sich absichtlich. | | [`POST /v2/distill`](/de/docs/coming-soon/distill.md) | Eine abgeschlossene URL. | | [`POST /v2/discover`](/de/docs/coming-soon/discover.md) | Ein Aufruf, unabhängig von der Größe der Site. | | [`POST /v2/watch`](/de/docs/coming-soon/watch.md) | Nichts. Watcher kosten null Ops. Sie sind stattdessen in der Anzahl gedeckelt. | 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](/de/docs/coming-soon.md). 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](/de/pricing.md) und auf einer Rechnung siehst. | Plan | Slug | Ops pro Monat | Max. Upload | Artefakt-Aufbewahrung | Batch-Limit | Overage | |------|------|---------------|------------|--------------------|-------------|---------| | Founding | `free` | 500 | 5 MB | 1 Stunde | Batch nicht verfügbar | Nicht verfügbar | | Indie | `starter` | 3.000 | 15 MB | 7 Tage | 50 URLs pro Batch | $0.02/Op, zuschaltbar | | Studio | `pro` | 15.000 | 50 MB | 7 Tage | 100 URLs pro Batch | $0.02/Op, zuschaltbar | | Production | `business` | 50.000 | 150 MB | 30 Tage | 400 URLs pro Batch | $0.02/Op, zuschaltbar | 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](/de/docs/endpoints/ingest.md) 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](/de/docs/concepts/signed-urls.md). ### Kontingente, die keine Ops sind Zwei Zuteilungen stehen neben dem Ops-Zähler und greifen nie darauf zu. | Plan | AI-Credits pro Monat | Aktive Watcher | |------|----------------------|-----------------| | Founding | $0 | Watch nicht verfügbar | | Indie | $5 | 20 | | Studio | $15 | 100 | | Production | $40 | 500 | 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": "..."}`. ```json { "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue." } ``` Auf diesem Pfad gibt es drei Meldungen: | Meldung | Bedingung | |---------|-----------| | `Monthly operations limit reached ({used}/{limit}). Upgrade your plan to continue.` | Der Zähler hat das Kontingent des Plans erreicht. | | `This request needs {units} operations but only {remaining} of your {limit} monthly operations remain. Upgrade your plan to continue.` | Eine Batch- oder Multi-URL-Anfrage ist größer als das, was übrig ist. Die gesamte Anfrage wird abgelehnt. | | `No active billing period found for this project. Contact support to restore your subscription.` | Es existiert keine Nutzungsperiode, und es konnte auch keine angelegt werden. Das Gate schlägt fail-closed fehl, statt eine kostenlose Op zu gewähren. | 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`: ```json { "detail": "Rate limit exceeded. Please slow down and retry shortly." } ``` Sie trägt vier Header: | Header | Bedeutung | |--------|---------| | `RateLimit-Limit` | Anfragen, die in dem Fenster erlaubt sind, das ausgelöst hat. | | `RateLimit-Remaining` | Verbleibende Anfragen in diesem Fenster, bei einer Ablehnung `0`. | | `RateLimit-Reset` | Sekunden, bis dieses Fenster zurückgesetzt wird. | | `Retry-After` | Dieselbe Zahl wie `RateLimit-Reset`. So lange warten, dann erneut versuchen. |
Diese Header erscheinen nur beim 429. Eine erfolgreiche Antwort trägt keine RateLimit-*-Header, und die API sendet nie die Schreibweise X-RateLimit-*. Baue keinen Client, der sein Budget aus einer 200 liest.
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`. ```json { "detail": { "error": "File too large", "file_size": 10485760, "max_size": 5242880, "tier": "free", "key_type": "private" } } ``` | Feld | Beschreibung | |-------|-------------| | `error` | Immer `"File too large"`. | | `file_size` | Größe der hochgeladenen Datei in Bytes. | | `max_size` | Die Obergrenze deines Plans in Bytes. | | `tier` | Dein Plan-Slug, mit Rückfall auf `"free"`, wenn sich kein Plan auflösen lässt. | | `key_type` | `"private"`, `"public"` oder `"dashboard"`, mit Rückfall auf `"unknown"`. | `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 | Meldung | Bedingung | |---------|-----------| | `Batch processing is not available on your current plan. Please upgrade to access this feature.` | Mehr als eine URL gesendet, auf einem Plan ohne Batch-Kontingent. | | `Batch size {N} exceeds your plan's limit of {M} URLs per batch.` | Die URL-Anzahl liegt über dem Batch-Limit des Plans. Teile die Liste auf und sende sie in Teilen. | | `Async processing is not available on your current plan. Please upgrade to access this feature.` | `async_mode=true` ohne Async-Zugriff. | | `Webhook callbacks is not available on your current plan. Please upgrade to access this feature.` | `callback_url` ohne Webhook-Zugriff. | | `ZIP output bundling is not available on your current plan. Please upgrade to access this feature.` | `output_format: true` ohne ZIP-Zugriff. Das Request-Feld ist ein Boolean; `"zip"` und `"individual"` sind die Werte, die in der Antwort zurückkommen. | | `Basic authentication, cookies & custom headers is not available on your current plan. Please upgrade to access this feature.` | `auth`, `cookies` oder `headers` ohne diesen Zugriff. | | `Website crawling is not available on your current plan. Please upgrade to access this feature.` | `website-to-pdf` oder `website-to-screenshot` auf einem Plan ohne Crawl-Zugriff. | | `Full website crawling requires a Studio plan or higher. Your plan supports sitemap-based crawling only.` | `crawl_mode: "full"` auf einem Plan, der URLs nur aus `sitemap.xml` ermittelt. | ### 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: | Meldung | Bedingung | |---------|-----------| | `{Feature} is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.` | Der Endpunkt ist für deinen Plan deaktiviert. | | `Active watcher limit reached ({active_count}/{limit}). Delete an existing watcher or upgrade your plan to add more.` | Das Projekt hält bereits seine maximale Anzahl aktiver Watcher. | | `Storage limit reached. Delete files or upgrade your storage plan to continue.` | Das Kontingent des Storage-Add-ons ist voll. | ### 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](/de/docs/reference/errors.md) enthält jeden Statuscode und jede Meldung, die die API zurückgeben kann. - [Batch-Verarbeitung](/de/docs/guides/batch-processing.md) behandelt, wie das Batch-Limit mit ZIP-Ausgabe und Polling zusammenspielt. - [Datei-Ingestion](/de/docs/guides/file-ingestion.md) behandelt die Upload-Pfade, für die die Größenobergrenze gilt. - [Signierte URLs](/de/docs/concepts/signed-urls.md) behandelt das 15-Minuten-Download-Fenster, das innerhalb deines Aufbewahrungsfensters liegt.