Formatos, limites, erros
Formatos suportados
Documentos e imagens (reconhecimento de texto, 16 formatos):
.pdf · .doc · .docx · .xls · .xlsx · .ppt · .pptx · .jpg · .jpeg · .png · .tiff · .tif · .heic · .txt · .rtf · .odt
Arquivos compactados e contêineres (descompactação recursiva, profundidade ≤ 3; 5 formatos):
.zip · .7z · .rar · .eml · .msg (e-mails do Outlook são convertidos para .eml)
Arquivos dentro de um arquivo compactado cuja extensão não esteja na lista não são processados (são ignorados silenciosamente durante a descompactação). Arquivos de assinatura digital (.sig, .sign) e arquivos sem extensão não são processados.
Não encontrou o formato de que precisa? Escreva para hello@hotdoc.io — nós o adicionamos gratuitamente.
Limites
Os valores abaixo são padrões; podem variar no seu deployment/plano.
| Limite | Valor | Escopo |
|---|---|---|
| Tamanho total do job | 300 MiB (padrão, configurável) | verificado antes e depois de cada source |
Tamanho de upload (POST /v1/jobs/upload e gRPC Upload) | 20 MiB (config grpc.maxRecvMsgBytes) | por arquivo/mensagem |
| Tamanho de um único source baixado | 20 MiB (padrão) | por arquivo |
| Número de arquivos de entrada por job | 20 (padrão) | sourceUrls |
| Número de arquivos descompactados | 20 (padrão) | após a descompactação |
| Jobs concorrentes por conta | 5 (padrão) | em andamento |
| Tamanho da resposta do conversor | 64 MiB | por arquivo |
| Timeout do conversor | 90 s | por arquivo |
| Timeout de download do source | 30 s, ≤ 3 redirecionamentos | por source |
| Retentativas de OCR | 3 tentativas × 10 s | por arquivo |
| Profundidade de descompactação de arquivos | ≤ 3 (padrão) | recursiva |
| Tamanho máximo do prompt | 64 KiB | excedê-lo → erro 400 |
| Taxa de requisições | 120 req/min por principal (burst 40), por réplica | chave de API ou usuário |
Códigos de erro
A API usa códigos HTTP padrão. O code no corpo da resposta é o código gRPC numérico (por exemplo, 8 = ResourceExhausted). Nos endpoints REST (exceto POST /v1/jobs/upload), o corpo é {"code": <int>, "message": "…", "details": [...]}. Para POST /v1/jobs/upload, é {"code": <int>, "message": "…"}, sem details.
| Código | Quando acontece |
|---|---|
400 | requisição inválida: prompt maior que 64 KiB, neural.type desconhecido, model/apiKey vazio, ocr.provider ausente / ocr.model vazio / ocr.providerKey vazio, reasoningEffort inválido, neural.chunkBudgetTokens fora da faixa 16000–2000000, criação de uma chave com expiresAt no passado ou idempotency key reused with different request parameters |
401 | token ausente ou não reconhecido (sem cabeçalho Authorization, ou o prefixo Bearer está faltando) |
403 | token ou chave inválido, ou a ação é proibida; isso inclui o uso de uma chave/token expirado, revogado ou não verificado |
404 | o job ou a chave não pertence à sua conta |
429 | três causas (todas gRPC ResourceExhausted): (1) cota do plano gratuito esgotada — message: "job quota exceeded" mais um QuotaExceededDetail{ jobsUsed, jobsLimit }; (2) limite de jobs concorrentes excedido — message: "too many concurrent jobs" (sem details); (3) limite de taxa excedido — em gRPC/REST a message traz "<method> is rejected by grpc_ratelimit middleware, please retry later. rate limit exceeded", e em POST /v1/jobs/upload é message: "rate limit exceeded" (sem details). |
5xx | erro interno do serviço; tente novamente com backoff exponencial |
Para distinguir os três casos de 429: cota — pela presença de QuotaExceededDetail; concorrência — pela substring too many concurrent jobs; taxa — pela substring grpc_ratelimit / rate limit exceeded.
Erros dentro de um job (um único arquivo não pôde ser processado) não são retornados como código HTTP — eles chegam no resultado do job no nível do arquivo, e o status do job passa a JOB_STATUS_PARTIAL (se ao menos um arquivo obteve uma resposta bem-sucedida do modelo) ou JOB_STATUS_FAILED (se nenhum obteve).
Os problemas do estágio de OCR aparecem como marcadores no nível do job (não como erros HTTP em tempo de criação); como o job termina depende do problema: Marcadores de autenticação/configuração que fazem o job inteiro falhar: provider_auth_failed, provider_key_required, provider_required, model_required, unsupported_provider. Marcadores permanentes por arquivo (esses arquivos falham, o job pode terminar como JOB_STATUS_PARTIAL): too_many_pages, unsupported_request, file_too_large, unsupported_format. Problemas transitórios do backend são repetidos internamente e não fazem o job falhar: rate_limited, ocr_backend_overloaded, ocr_backend_error, ocr_backend_unavailable, ocr_timeout. Erros de validação em tempo de criação (ocr.provider ausente, ocr.model vazio ou ocr.providerKey vazio) → 400 antes de o processamento começar.