Formate, Limits, Fehler
Unterstützte Formate
Dokumente und Bilder (Texterkennung, 16 Formate):
.pdf · .doc · .docx · .xls · .xlsx · .ppt · .pptx · .jpg · .jpeg · .png · .tiff · .tif · .heic · .txt · .rtf · .odt
Archive und Container (rekursives Entpacken, Tiefe ≤ 3; 5 Formate):
.zip · .7z · .rar · .eml · .msg (Outlook-E-Mails werden in .eml konvertiert)
Dateien innerhalb eines Archivs, deren Erweiterung nicht auf der Liste steht, werden nicht verarbeitet (sie werden beim Entpacken stillschweigend übersprungen). Dateien mit digitaler Signatur (.sig, .sign) und Dateien ohne Erweiterung werden nicht verarbeitet.
Sie finden das benötigte Format nicht? Schreiben Sie an hello@hotdoc.io — wir fügen es kostenlos hinzu.
Limits
Die folgenden Werte sind Standardwerte; sie können in Ihrem Deployment/Tarif abweichen.
| Limit | Wert | Geltungsbereich |
|---|---|---|
| Gesamtgröße eines Jobs | 300 MiB (Standard, konfigurierbar) | vor und nach jeder Source geprüft |
Upload-Größe (POST /v1/jobs/upload und gRPC Upload) | 20 MiB (Konfiguration grpc.maxRecvMsgBytes) | pro Datei/Nachricht |
| Größe einer einzelnen heruntergeladenen Source | 20 MiB (Standard) | pro Datei |
| Anzahl der Eingabedateien pro Job | 20 (Standard) | sourceUrls |
| Anzahl der entpackten Dateien | 20 (Standard) | nach dem Entpacken |
| Gleichzeitige Jobs pro Konto | 5 (Standard) | in Bearbeitung |
| Größe der Konverter-Antwort | 64 MiB | pro Datei |
| Konverter-Timeout | 90 s | pro Datei |
| Source-Download-Timeout | 30 s, ≤ 3 Weiterleitungen | pro Source |
| OCR-Wiederholungen | 3 Versuche × 10 s | pro Datei |
| Tiefe des Archiv-Entpackens | ≤ 3 (Standard) | rekursiv |
| Maximale Prompt-Größe | 64 KiB | Überschreitung → 400-Fehler |
| Anfragerate | 120 req/min pro Principal (Burst 40), pro Replica | API-Schlüssel oder Benutzer |
Fehlercodes
Die API verwendet Standard-HTTP-Codes. Der code im Antwort-Body ist der numerische gRPC-Code (zum Beispiel 8 = ResourceExhausted). Bei REST-Endpunkten (außer POST /v1/jobs/upload) ist der Body {"code": <int>, "message": "…", "details": [...]}. Bei POST /v1/jobs/upload ist er {"code": <int>, "message": "…"}, ohne details.
| Code | Wann er auftritt |
|---|---|
400 | fehlerhafte Anfrage: Prompt größer als 64 KiB, unbekannter neural.type, leeres model/apiKey, fehlendes ocr.provider / leeres ocr.model / leeres ocr.providerKey, ungültiges reasoningEffort, neural.chunkBudgetTokens außerhalb des Bereichs 16000–2000000, Erstellung eines Schlüssels mit expiresAt in der Vergangenheit oder idempotency key reused with different request parameters |
401 | Token fehlt oder ist nicht erkennbar (kein Authorization-Header oder das Bearer-Präfix fehlt) |
403 | Token oder Schlüssel ist ungültig oder die Aktion ist verboten; dazu gehört die Verwendung eines abgelaufenen, widerrufenen oder nicht verifizierten Schlüssels/Tokens |
404 | der Job oder Schlüssel gehört nicht zu Ihrem Konto |
429 | drei Ursachen (alle gRPC ResourceExhausted): (1) Kontingent des kostenlosen Tarifs erschöpft — message: "job quota exceeded" plus ein QuotaExceededDetail{ jobsUsed, jobsLimit }; (2) Limit gleichzeitiger Jobs überschritten — message: "too many concurrent jobs" (kein details); (3) Ratenlimit überschritten — bei gRPC/REST lautet die message "<method> is rejected by grpc_ratelimit middleware, please retry later. rate limit exceeded", und bei POST /v1/jobs/upload ist es message: "rate limit exceeded" (kein details). |
5xx | interner Dienstfehler; mit exponentiellem Backoff erneut versuchen |
So unterscheiden Sie die drei 429-Fälle: Kontingent — am Vorhandensein von QuotaExceededDetail; Parallelität — am Teilstring too many concurrent jobs; Rate — am Teilstring grpc_ratelimit / rate limit exceeded.
Fehler innerhalb eines Jobs (eine einzelne Datei konnte nicht verarbeitet werden) werden nicht als HTTP-Code zurückgegeben — sie erscheinen im Job-Ergebnis auf Dateiebene, und der Job-Status wird zu JOB_STATUS_PARTIAL (wenn mindestens eine Datei eine erfolgreiche Modellantwort erhielt) oder JOB_STATUS_FAILED (wenn keine).
Probleme in der OCR-Stufe treten als Marker auf Job-Ebene auf (keine HTTP-Fehler beim Erstellen); wie der Job endet, hängt vom Problem ab: Auth-/Konfigurationsmarker, die den ganzen Job scheitern lassen: provider_auth_failed, provider_key_required, provider_required, model_required, unsupported_provider. Permanente Marker auf Dateiebene (diese Dateien scheitern, der Job kann mit JOB_STATUS_PARTIAL enden): too_many_pages, unsupported_request, file_too_large, unsupported_format. Vorübergehende Backend-Probleme werden intern wiederholt und führen nicht zum Scheitern des Jobs: rate_limited, ocr_backend_overloaded, ocr_backend_error, ocr_backend_unavailable, ocr_timeout. Validierungsfehler beim Erstellen (fehlendes ocr.provider, leeres ocr.model oder leeres ocr.providerKey) → 400, bevor die Verarbeitung beginnt.