Форматы, лимиты, ошибки
Поддерживаемые форматы
Документы и изображения (распознавание текста, 16 форматов):
.pdf · .doc · .docx · .xls · .xlsx · .ppt · .pptx · .jpg · .jpeg · .png · .tiff · .tif · .heic · .txt · .rtf · .odt
Архивы и контейнеры (рекурсивная распаковка, глубина ≤ 3; 5 форматов):
.zip · .7z · .rar · .eml · .msg (Outlook-письма конвертируются в .eml)
Файлы внутри архива с расширением вне списка не обрабатываются (молча пропускаются при распаковке). Файлы электронной подписи (.sig, .sign) и файлы без расширения не обрабатываются.
Нужного формата нет в списке? Напишите на hello@hotdoc.io – добавим бесплатно!
Лимиты
Значения ниже — по умолчанию; в вашем деплое/тарифе могут отличаться.
| Лимит | Значение | Область действия |
|---|---|---|
| Суммарный размер задачи | 300 MiB (по умолчанию, конфигурируемо) | проверяется до и после каждого источника |
Размер загрузки (POST /v1/jobs/upload и gRPC Upload) | 20 MiB (конфиг grpc.maxRecvMsgBytes) | на файл/сообщение |
| Размер одного скачиваемого источника | 20 MiB (по умолчанию) | на файл |
| Число входных файлов в задаче | 20 (по умолчанию) | sourceUrls |
| Число распакованных файлов | 20 (по умолчанию) | после распаковки |
| Конкурентных задач на аккаунт | 5 (по умолчанию) | in-flight |
| Размер ответа конвертера | 64 MiB | на файл |
| Таймаут конвертера | 90 с | на файл |
| Таймаут скачивания источника | 30 с, ≤ 3 редиректов | на источник |
| Повторы OCR | 3 попытки × 10 с | на файл |
| Глубина распаковки архивов | ≤ 3 (по умолчанию) | рекурсивно |
| Максимальный размер промпта | 64 KiB | превышение → ошибка 400 |
| Частота запросов | 120 req/мин на принципал (burst 40), per-replica | API-ключ или пользователь |
Коды ошибок
API использует стандартные HTTP-коды. code в теле ответа — числовой gRPC-код (например, 8 = ResourceExhausted). На REST-эндпоинтах (кроме POST /v1/jobs/upload) тело: {"code": <int>, "message": "…", "details": [...]}. У POST /v1/jobs/upload — {"code": <int>, "message": "…"} без details.
| Код | Когда возникает |
|---|---|
400 | некорректный запрос: промпт больше 64 KiB, неизвестный neural.type, пустые model/apiKey, отсутствует ocr.provider / пустой ocr.model / пустой ocr.providerKey, невалидный reasoningEffort, neural.chunkBudgetTokens вне диапазона 16000–2000000, создание ключа с expiresAt в прошлом или idempotency key reused with different request parameters |
401 | токен не передан или не распознан (нет заголовка Authorization либо отсутствует префикс Bearer) |
403 | токен или ключ невалиден, либо действие запрещено; в том числе использование истёкшего, отозванного или не прошедшего верификацию ключа/токена |
404 | задача или ключ не принадлежат вашему аккаунту |
429 | три причины (все — gRPC ResourceExhausted): (1) исчерпана квота free-тарифа — message: "job quota exceeded" + деталь QuotaExceededDetail{ jobsUsed, jobsLimit }; (2) превышен лимит конкурентных задач — message: "too many concurrent jobs" (без details); (3) превышен лимит частоты запросов — на gRPC/REST message имеет вид "<method> is rejected by grpc_ratelimit middleware, please retry later. rate limit exceeded", на POST /v1/jobs/upload — message: "rate limit exceeded" (без details). |
5xx | внутренняя ошибка сервиса; повторите запрос с экспоненциальной паузой |
Различать три случая 429: квота — по наличию QuotaExceededDetail; конкурентность — по подстроке too many concurrent jobs; частота — по подстроке grpc_ratelimit / rate limit exceeded.
Ошибки внутри задачи (отдельный файл не обработался) не возвращаются HTTP-кодом — они приходят в результате задачи на уровне файла, а статус задачи становится JOB_STATUS_PARTIAL (если хотя бы один файл получил успешный ответ модели) или JOB_STATUS_FAILED (если ни один).
Проблемы на OCR-стадии проявляются как маркеры на уровне задачи (не HTTP-ошибки при создании); исход задачи зависит от типа проблемы: Маркеры, завершающие задачу целиком: provider_auth_failed, provider_key_required, provider_required, model_required, unsupported_provider. Постоянные маркеры на уровне файла (файлы падают, задача может завершиться JOB_STATUS_PARTIAL): too_many_pages, unsupported_request, file_too_large, unsupported_format. Транзитные проблемы бэкенда повторяются автоматически и не приводят к провалу задачи: rate_limited, ocr_backend_overloaded, ocr_backend_error, ocr_backend_unavailable, ocr_timeout. Ошибки валидации при создании (отсутствует ocr.provider, пустой ocr.model или пустой ocr.providerKey) → 400 до начала обработки.