EnConvert API-Fehlercodes#

Diese Referenz listet die HTTP-Statuscodes und Fehlermeldungen auf, die die EnConvert API zurückgibt: von 200 OK für synchrone Konvertierungen und 202 Accepted für async- und Batch-Jobs bis zu den unten dokumentierten Fehlerantworten. Jeder Fehlerabschnitt listet die genauen Meldungstexte, die Bedingung, die den jeweiligen Fehler auslöst, und wie du den Request korrigierst. Fehler-Bodies haben nicht alle dieselbe Form: es gibt sechs davon, und der Abschnitt Format der Fehlerantwort zeigt jede einzelne.

Ein Job, der nach seiner Annahme scheitert, ist kein HTTP-Fehler. Der 202 bleibt bestehen, und der Fehlschlag erscheint im Status-Payload des Jobs, wenn du ihn abfragst; beschrieben unter Sync- und async-Jobs.

HTTP-Statuscodes#

Format der Fehlerantwort#

Es gibt sechs Body-Formen. Welche du bekommst, hängt davon ab, wo der Fehler auftrat, nicht allein vom Statuscode. Prüfe also den Typ von detail, bevor du ihn ausliest.

1. detail als String. Der Normalfall und die einzige Form, die die meisten Integrationen überhaupt zu sehen bekommen.

{
    "detail": "Authentication required"
}

2. detail als Objekt. Der 413 zum Dateigrößenlimit des Plans. Das strukturierte Objekt ist der Wert von detail, lies also body.detail.max_size, nicht body.max_size. Siehe 413 Payload Too Large.

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

3. detail als Array plus errors. Die Schema-Validierung (422) gibt beides zurück: detail ist die rohe Ausgabe des Validators, errors ist ein paralleles Array aus menschenlesbaren Strings. Siehe 422 Unprocessable Entity.

4. Typisierter Konvertierungs-Envelope. {"error", "code", "detail"}, mit einem maschinenlesbaren code. Wird nur von den drei V1-URL-Konvertierungs-Endpunkten ausgegeben. Siehe Browser-Konvertierungsfehler.

5. Unbehandelte Exception. Ein 500, der nicht von einem Konverter stammt, hat überhaupt kein detail:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

6. Gateway-Request-Timeout. Das eigene 300-Sekunden-Budget des Gateways erzeugt einen 504 ohne detail und ohne code:

{
    "error": "Request timeout"
}

400 Bad Request#

Wird zurückgegeben, wenn der Request ungültige Parameter, fehlende Felder oder fehlerhafte Daten enthält.

Eingabevalidierung#

Batch- und Modus-Validierung#

Validierung von Auth, Cookies & Headern#

URL-Sicherheit (SSRF)#

Jeder URL-basierte Endpunkt prüft die Ziel-url, bevor er sie abruft. Diese Meldungen werden als 400 zurückgegeben, wenn die URL keine öffentliche http(s)-Adresse ist.

Validierung der Rendering-Optionen#

Sitemap- und Crawl-Fehler#

Fehler beim Konvertierungsinhalt#

401 Unauthorized#

Wird zurückgegeben, wenn die Authentifizierung fehlt oder ungültig ist.

402 Payment Required#

Wird zurückgegeben, wenn ein Nutzungslimit überschritten wird. Die Aufteilung zwischen 402 und 403 ist nicht symmetrisch, und sie führt regelmäßig in die Irre. Jede Kontingent-Bedingung antwortet mit 402, ebenso ein V2-Endpunkt, der in deinem Plan abgeschaltet ist. V1-Feature-Gates antworten mit 403 (async, Webhooks, ZIP-Ausgabe, Basic Auth, Batch). Rate-Limiting ist ein separater Mechanismus und antwortet mit 429, nie mit 402.

Aufgebrauchte monatliche AI-Credits erzeugen keinen 402. Die Schema-Extraktion fällt auf das heuristische und CSS-basierte Ergebnis zurück, und der Request ist trotzdem erfolgreich. Kontingente, Preise und was als eine Operation zählt, stehen unter Rate-Limits und Kontingente.

403 Forbidden#

Wird zurückgegeben, wenn der Zugriff aufgrund von Key-Typ, Domain, V1-Plan-Funktion oder Endpunkt-Beschränkungen verweigert wird. V2-Endpunkt-Gates sind die Ausnahme: Sie antworten mit 402, nicht mit 403.

Beschränkungen für API-Keys und Token#

Plan-Funktionsbeschränkungen#

Widget-Beschränkungen#

Zwei weitere 403-Meldungen betreffen weder Keys noch Pläne: Account suspended, zurückgegeben für jeden Request, sobald das Konto hinter dem Key oder Token gesperrt ist, und robots.txt disallows fetching this URL (request sent respect_robots=true)., zurückgegeben von perceive, wenn du robots-Konformität angefordert hast und das Ziel den Pfad verbietet.

404 Not Found#

409 Conflict#

410 Gone#

Das Artefakt existierte, hat aber das Aufbewahrungsfenster für Dateien deines Plans überschritten und liegt nicht mehr im Speicher. Die Aufbewahrung ist planabhängig; siehe Rate-Limits und Kontingente.

Behandle 410 für dieses Objekt als endgültig. Ein erneuter Lauf des Requests erzeugt ein frisches Artefakt; ein erneuter Download-Versuch nicht.

413 Payload Too Large#

Wird zurückgegeben, wenn die hochgeladene Datei die maximale Dateigröße des Plans überschreitet.

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

Das Limit wird gegen die exakte Bytezahl des hochgeladenen Teils geprüft, bevor irgendeine Konvertierungsarbeit beginnt. Eine Datei, die exakt max_size groß ist, wird akzeptiert; nur eine größere Datei wird abgelehnt. Der Content-Length-Header ist ein Fallback für ältere Aufrufstellen, die ihr Upload-Objekt nicht an die Prüfung übergeben.

POST /v2/ingest/files verwendet diese Form nicht. Der Endpunkt antwortet mit 413 und einem einfachen String-detail: File '{filename}' exceeds the {max_size}-byte limit.

Die Obergrenzen pro Plan stehen unter Rate-Limits und Kontingente, und die Upload-Pfade, für die das gilt, stehen unter Datei-Ingestion.

Browser-Konvertierungsfehler (415 / 422 / 502 / 504)#

URL-Konvertierungen unterscheiden einen Fehler in der Zielseite oder der Eingabe (ein 4xx, 502 oder 504, auf den du reagieren kannst) von einem Fehler in unserer Engine (ein 500). Die drei V1-URL-Konvertierungs-Endpunkte (url-to-pdf, url-to-screenshot, url-to-markdown) geben diese typisierten Fehlschläge mit einem maschinenlesbaren code neben detail zurück:

{
    "error": "Gateway Timeout",
    "code": "upstream_timeout",
    "detail": "The target site took too long to respond while rendering PDF for https://example.com."
}

Diese fünf sind das gesamte Vokabular. Keine andere Endpunkt-Familie gibt einen code aus, V2 eingeschlossen: Ein V2-Fehlschlag kommt als einfacher detail-String zurück. Die Basisklasse des Envelopes definiert einen sechsten Slug, conversion_error, aber nichts löst ihn aus, sodass er dich nie erreicht. Verzweige auf die obigen fünf und behandle jeden anderen Wert als unbekannt.

Ein 504 kann auch in zwei untypisierten Formen ankommen: {"error": "Request timeout"}, wenn der Request das 300-Sekunden-Budget des Gateways überdauert, und ein einfacher detail-String mit der Timeout-Meldung, wenn eine Dokumentkonvertierung (LibreOffice) in ein Timeout läuft. Keine der beiden trägt einen code.

422 Unprocessable Entity#

Schema-Validierungsfehler geben zwei parallele Arrays zurück. detail ist die rohe Ausgabe des Validators und damit das, was du auf Formularfelder zurückmappst. errors ist ein menschenlesbarer String pro Problem und damit das, was du einem Nutzer anzeigst.

{
    "detail": [
        {
            "loc": ["body", "max_pages"],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "type": "int_parsing"
        }
    ],
    "errors": [
        "body.max_pages: Input should be a valid integer, unable to parse string as an integer (you sent 'ten')"
    ]
}

Drei type-Werte lohnt es sich, namentlich zu behandeln:

Ein 422 mit dem Code selector_not_found ist etwas anderes: eine fehlgeschlagene Rendering-Vorbedingung, behandelt unter Browser-Konvertierungsfehler.

429 Too Many Requests#

Rate-Limiting ist eine Fairness-Kontrolle über ein kurzes Zeitfenster und vom monatlichen Ops-Kontingent getrennt. Ein erschöpftes Kontingent antwortet mit 402; nur der Rate-Limiter antwortet mit 429.

Ein 429 trägt vier Header:

Diese Header erscheinen nur beim 429. Erfolgreiche Antworten tragen weder Rate-Limit-Header noch Header zu verbleibenden Ops. Du kannst dein Restbudget also nicht aus einer Antwort ablesen; prüfe die Nutzung im Dashboard. Siehe Rate-Limits und Kontingente.

500 Internal Server Error#

Alles, was außerhalb eines Konverters ausfällt, erreicht dich nie als Text. Es kommt ganz ohne detail zurück:

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

Ein Fall überrascht regelmäßig: Ein fehlerhafter JSON-Body an einen V1-URL-Endpunkt (url-to-pdf, url-to-screenshot, url-to-markdown, website-to-pdf, website-to-screenshot) gibt diesen 500 zurück statt eines 422, weil diese Endpunkte den rohen Body lesen. Derselbe fehlerhafte Body an einem V2-Endpunkt gibt einen 422 mit type: json_invalid zurück.

Wenn du anhaltende 500-Fehler erlebst, liegt das Problem wahrscheinlich an der Eingabedatei oder URL. Versuche es mit einer anderen Eingabe, um das Problem einzugrenzen.

503 Service Unavailable#

Es gibt zwei verschiedene Kapazitäts-Gates, und sie verlangen unterschiedliche Wartezeiten. Lies also Retry-After, statt eine Wartezeit anzunehmen. Ansonsten sind diese Fehler vorübergehend: wiederhole den Request nach kurzer Verzögerung.

V2-Endpunkt-Fehler#

Die V2 Web-Intelligence-Endpunkte verwenden die obigen Statuscodes erneut, mit einigen V2-spezifischen Bedingungen, die hervorzuheben sind.

Quota und Plan (402 / 403)#

V2-Operationen werden gegen dasselbe einheitliche monatliche Ops-Kontingent verrechnet wie V1-Konvertierungen: eine Op pro Arbeitseinheit. Jeder kostenpflichtige Plan mit aktivierter Überschreitung ($0.02/Op) erlaubt es, das Kontingent zu übersteigen; sonst ist die Grenze hart.

Zwei V2-Verhalten sind bewusst keine Fehler. Ein aufgebrauchtes AI-Credit-Guthaben lässt den Request nicht scheitern: Die Schema-Extraktion fällt auf das heuristische und CSS-basierte Ergebnis zurück. Und ein distill-Lauf über mehrere URLs, der mittendrin die Ops-Grenze überschreitet, gibt ebenfalls keinen 402: Er stoppt dort, gibt die fertig verarbeiteten URLs zurück und hängt eine Warnung an, die nennt, wie viele übersprungen wurden.

Validierung (422)#

Jedes V2-Request-Schema weist unbekannte Schlüssel zurück, ein falsch geschriebener Parameter ist also ein 422, der das Feld benennt. Die Body-Form ist unter 422 Unprocessable Entity beschrieben.

Such-Provider (502 / 503)#

Der lookup-Endpunkt hängt von einem vorgelagerten Such-Provider ab. Roher Fehlertext des Providers erreicht den Client nie.

Nicht gefunden (404)#

GET und DELETE auf eine V2-operation_id, job_id oder watcher_id, die nicht existiert oder die zu einem anderen Projekt gehört, gibt 404 zurück. Existenz wird niemals projektübergreifend preisgegeben.

Angenommen (202)#

Ingest ist immer asynchron: POST /v2/ingest antwortet mit 202 und einer job_id, die du abfragst. Perceive-Batches mit mehr als 10 URLs antworten mit 202 und Status queued. Ein Batch mit 10 oder weniger URLs antwortet normalerweise inline, aber wenn er das Inline-Fenster überschreitet, fällt er auf 202 mit Status processing und einer Warnung zurück. Behandle 202 also bei jeder Batch-Größe.

Ein 202 bedeutet außerdem, dass spätere Fehlschläge keine HTTP-Fehler sind. Frage den Job ab und lies seinen Status-Payload, wie unter Sync- und async-Jobs beschrieben.

Fehlerbehebung#

Authentifizierungsprobleme#

• Bekommst du 401? Prüfe, ob dein API-Key gültig und im Dashboard aktiv ist. Bei Verwendung von JWT stelle sicher, dass das Token nicht abgelaufen ist (1-Stunden-Gültigkeit).
• Bekommst du 403 zur Browser-Nutzung? Du verwendest einen Private-Key (sk_...) aus clientseitigem Code. Wechsle für browserbasierte Requests zu einem Public-Key mit JWT.
• Bekommst du 403 zur Domain? Füge deine Domain im Dashboard zur Liste der erlaubten Domains des API-Keys hinzu.

Konvertierungsprobleme#

• Bekommst du 400 zum Dateiformat? Stelle sicher, dass die Erweiterung der hochgeladenen Datei zum Endpunkt passt (z. B. .json für json-to-xml, .docx für doc-to-pdf).
• Bekommst du 413? Deine Datei überschreitet das Größenlimit des Plans. Lies detail.max_size aus der Antwort und prüfe dann die maximale Dateigröße deines Plans oder führe ein Upgrade durch.
• Bekommst du 402? Du hast dein monatliches Ops-Kontingent, die Watcher-Obergrenze oder das Speicherlimit erreicht, oder das Projekt hat keinen aktiven Abrechnungszeitraum. Prüfe die Nutzung im Dashboard und siehe Rate-Limits und Kontingente.

Probleme beim Funktionszugriff#

• Bekommst du 403 zu Plan-Funktionen? Die V1-Funktion, die du verwenden möchtest (async, Batch, Webhooks, ZIP-Ausgabe, Basic Auth), erfordert eine höhere Plan-Stufe. Siehe die Feature-Gating-Tabelle.
• Bekommst du 402 an einem V2-Endpunkt, ohne dass es um Kontingente geht? V2-Endpunkt-Gates antworten mit 402, nicht mit 403. Die Meldung lautet ... is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.

Häufig gestellte Fragen#

Warum gibt die API bei einer Dateikonvertierung 402 Payment Required zurück?#

Ein 402 bedeutet, dass ein Nutzungslimit ausgeschöpft ist: dein einheitliches monatliches Ops-Kontingent (500 Ops im Founding-Plan), die Obergrenze für aktive Watcher oder die Speicherzuteilung deines Projekts. Er deckt außerdem zwei Fälle ab, die nichts mit Kontingenten zu tun haben: ein Projekt ohne aktiven Abrechnungszeitraum und ein V2-Endpunkt, der in deinem Plan abgeschaltet ist. Batch-Requests, die das verbleibende monatliche Ops-Kontingent überschreiten würden, werden vorab mit einem 402 für den gesamten Batch abgelehnt. V1-Konvertierungen und V2-Operationen schöpfen aus demselben Kontingent; jeder kostenpflichtige Plan mit aktivierter Überschreitung ($0.02/Op) erlaubt es, darüber hinauszugehen. Rate-Limiting ist ein anderer Mechanismus und antwortet mit 429.

Wie behebe ich einen 401-Unauthorized-Fehler der Konvertierungs-API?#

Prüfe, ob der API-Key vorhanden ist, mit sk_ oder pk_ beginnt und im Dashboard noch aktiv ist, denn widerrufene Keys geben API Key revoked zurück. Wenn du dich mit einem JWT authentifizierst, beachte, dass Access-Tokens nach 1 Stunde ablaufen (Token has expired) und Refresh-Tokens nach 7 Tagen.

Warum bekomme ich beim Hochladen einer Datei 413 Payload Too Large?#

Die hochgeladene Datei überschreitet die maximale Dateigröße deines Plans, gemessen an der exakten Bytezahl des hochgeladenen Teils, bevor irgendeine Konvertierungsarbeit beginnt. Eine Datei exakt am Limit wird akzeptiert. Der 413-Body verschachtelt ein strukturiertes Objekt unter detail, mit file_size, max_size (beide in Bytes), tier und key_type. Lies es also als detail.max_size und nicht als Top-Level-Feld.

Kann ich einen privaten API-Key aus Browser-JavaScript verwenden?#

Nein. Ein Private-Key (sk_...), der in einem Request mit einem Browser-Origin-Header verwendet wird, gibt 403 Private API keys cannot be used from browsers zurück. Tausche einen Public-Key unter /v1/auth/token gegen ein JWT ein und verwende dieses Token für browserbasierte API-Aufrufe.

Ist ein 503-Service-Unavailable-Fehler der API dauerhaft?#

Nein, 503-Fehler wie Converter not available: {endpoint} oder Turnstile verification unavailable sind in der Regel vorübergehend. Wiederhole den Request nach kurzer Verzögerung.