Formatos, límites y errores
Formatos admitidos
Documentos e imágenes (reconocimiento de texto, 16 formatos):
.pdf · .doc · .docx · .xls · .xlsx · .ppt · .pptx · .jpg · .jpeg · .png · .tiff · .tif · .heic · .txt · .rtf · .odt
Archivos comprimidos y contenedores (descompresión recursiva, profundidad ≤ 3; 5 formatos):
.zip · .7z · .rar · .eml · .msg (los correos de Outlook se convierten a .eml)
Los archivos dentro de un comprimido cuya extensión no esté en la lista no se procesan (se omiten silenciosamente durante la descompresión). Los archivos de firma digital (.sig, .sign) y los archivos sin extensión no se procesan.
¿No ve el formato que necesita? Escriba a hello@hotdoc.io: lo añadimos gratis.
Límites
Los valores de abajo son los predeterminados; pueden variar según su despliegue/plan.
| Límite | Valor | Ámbito |
|---|---|---|
| Tamaño total de la tarea | 300 MiB (por defecto, configurable) | comprobado antes y después de cada origen |
Tamaño de subida (POST /v1/jobs/upload y gRPC Upload) | 20 MiB (config grpc.maxRecvMsgBytes) | por archivo/mensaje |
| Tamaño de un único origen descargado | 20 MiB (por defecto) | por archivo |
| Número de archivos de entrada por tarea | 20 (por defecto) | sourceUrls |
| Número de archivos descomprimidos | 20 (por defecto) | tras descomprimir |
| Tareas concurrentes por cuenta | 5 (por defecto) | en curso |
| Tamaño de la respuesta del conversor | 64 MiB | por archivo |
| Timeout del conversor | 90 s | por archivo |
| Timeout de descarga del origen | 30 s, ≤ 3 redirecciones | por origen |
| Reintentos de OCR | 3 intentos × 10 s | por archivo |
| Profundidad de descompresión de comprimidos | ≤ 3 (por defecto) | recursiva |
| Tamaño máximo del prompt | 64 KiB | superarlo → error 400 |
| Tasa de solicitudes | 120 req/min por principal (burst 40), por réplica | API key o usuario |
Códigos de error
La API usa códigos HTTP estándar. El code del cuerpo de la respuesta es el código numérico de gRPC (por ejemplo, 8 = ResourceExhausted). En los endpoints REST (excepto POST /v1/jobs/upload), el cuerpo es {"code": <int>, "message": "…", "details": [...]}. Para POST /v1/jobs/upload, es {"code": <int>, "message": "…"}, sin details.
| Código | Cuándo ocurre |
|---|---|
400 | solicitud incorrecta: prompt mayor de 64 KiB, neural.type desconocido, model/apiKey vacíos, falta ocr.provider / ocr.model vacío / ocr.providerKey vacío, reasoningEffort inválido, neural.chunkBudgetTokens fuera del rango 16000–2000000, crear una clave con expiresAt en el pasado o clave de idempotencia reutilizada con parámetros de solicitud diferentes |
401 | token ausente o no reconocido (sin cabecera Authorization, o falta el prefijo Bearer) |
403 | el token o la clave es inválido, o la acción está prohibida; esto incluye usar una clave/token caducado, revocado o no verificado |
404 | la tarea o la clave no pertenece a su cuenta |
429 | tres causas (todas gRPC ResourceExhausted): (1) cuota del plan gratuito agotada — message: "job quota exceeded" más un QuotaExceededDetail{ jobsUsed, jobsLimit }; (2) límite de tareas concurrentes superado — message: "too many concurrent jobs" (sin details); (3) límite de tasa superado — en gRPC/REST el message dice "<method> is rejected by grpc_ratelimit middleware, please retry later. rate limit exceeded", y en POST /v1/jobs/upload es message: "rate limit exceeded" (sin details). |
5xx | error interno del servicio; reintente con backoff exponencial |
Para distinguir los tres casos de 429: cuota — por la presencia de QuotaExceededDetail; concurrencia — por la subcadena too many concurrent jobs; tasa — por la subcadena grpc_ratelimit / rate limit exceeded.
Los errores dentro de una tarea (un solo archivo que no se pudo procesar) no se devuelven como código HTTP: llegan en el resultado de la tarea a nivel de archivo, y el estado de la tarea pasa a JOB_STATUS_PARTIAL (si al menos un archivo obtuvo una respuesta correcta del modelo) o JOB_STATUS_FAILED (si ninguno lo hizo).
Los problemas de la etapa OCR se manifiestan como marcadores a nivel de tarea (no como errores HTTP en tiempo de creación); cómo termina la tarea depende del problema: Marcadores de autenticación/configuración que hacen fallar toda la tarea: provider_auth_failed, provider_key_required, provider_required, model_required, unsupported_provider. Marcadores permanentes por archivo (esos archivos fallan, la tarea puede terminar en JOB_STATUS_PARTIAL): too_many_pages, unsupported_request, file_too_large, unsupported_format. Los problemas transitorios del backend se reintentan internamente y no se manifiestan como fallos de la tarea: rate_limited, ocr_backend_overloaded, ocr_backend_error, ocr_backend_unavailable, ocr_timeout. Los errores de validación en tiempo de creación (falta ocr.provider, ocr.model vacío o ocr.providerKey vacío) → 400 antes de que comience el procesamiento.