Formats, limites, erreurs
Formats pris en charge
Documents et images (reconnaissance de texte, 16 formats) :
.pdf · .doc · .docx · .xls · .xlsx · .ppt · .pptx · .jpg · .jpeg · .png · .tiff · .tif · .heic · .txt · .rtf · .odt
Archives et conteneurs (décompression récursive, profondeur ≤ 3 ; 5 formats) :
.zip · .7z · .rar · .eml · .msg (les e-mails Outlook sont convertis en .eml)
Les fichiers contenus dans une archive dont l’extension ne figure pas dans la liste ne sont pas traités (ils sont ignorés silencieusement lors de la décompression). Les fichiers de signature numérique (.sig, .sign) et les fichiers sans extension ne sont pas traités.
Vous ne trouvez pas le format dont vous avez besoin ? Écrivez à hello@hotdoc.io — nous l’ajouterons gratuitement.
Limites
Les valeurs ci-dessous sont les valeurs par défaut ; elles peuvent différer selon votre déploiement/forfait.
| Limite | Valeur | Portée |
|---|---|---|
| Taille totale du job | 300 MiB (par défaut, configurable) | vérifiée avant et après chaque source |
Taille d’envoi (POST /v1/jobs/upload et gRPC Upload) | 20 MiB (config grpc.maxRecvMsgBytes) | par fichier/message |
| Taille d’une source téléchargée | 20 MiB (par défaut) | par fichier |
| Nombre de fichiers en entrée par job | 20 (par défaut) | sourceUrls |
| Nombre de fichiers décompressés | 20 (par défaut) | après décompression |
| Jobs concurrents par compte | 5 (par défaut) | en cours |
| Taille de la réponse du convertisseur | 64 MiB | par fichier |
| Délai du convertisseur | 90 s | par fichier |
| Délai de téléchargement d’une source | 30 s, ≤ 3 redirections | par source |
| Tentatives OCR | 3 tentatives × 10 s | par fichier |
| Profondeur de décompression d’archive | ≤ 3 (par défaut) | récursive |
| Taille maximale d’un prompt | 64 KiB | dépassement → erreur 400 |
| Débit de requêtes | 120 req/min par principal (burst 40), par réplique | clé API ou utilisateur |
Codes d’erreur
L’API utilise les codes HTTP standard. Le code dans le corps de la réponse est le code numérique gRPC (par exemple, 8 = ResourceExhausted). Sur les endpoints REST (sauf POST /v1/jobs/upload), le corps est {"code": <int>, "message": "…", "details": [...]}. Pour POST /v1/jobs/upload, c’est {"code": <int>, "message": "…"}, sans details.
| Code | Quand cela se produit |
|---|---|
400 | requête invalide : prompt supérieur à 64 KiB, neural.type inconnu, model/apiKey vide, ocr.provider manquant / ocr.model vide / ocr.providerKey vide, reasoningEffort invalide, neural.chunkBudgetTokens hors de la plage 16000–2000000, création d’une clé avec un expiresAt dans le passé, ou idempotency key reused with different request parameters |
401 | jeton manquant ou non reconnu (absence d’en-tête Authorization, ou préfixe Bearer manquant) |
403 | jeton ou clé invalide, ou action interdite ; cela inclut l’utilisation d’une clé/d’un jeton expiré, révoqué ou non vérifié |
404 | le job ou la clé n’appartient pas à votre compte |
429 | trois causes (toutes gRPC ResourceExhausted) : (1) quota du forfait gratuit épuisé — message: "job quota exceeded" plus un QuotaExceededDetail{ jobsUsed, jobsLimit } ; (2) limite de jobs concurrents dépassée — message: "too many concurrent jobs" (sans details) ; (3) limite de débit dépassée — sur gRPC/REST le message indique "<method> is rejected by grpc_ratelimit middleware, please retry later. rate limit exceeded", et sur POST /v1/jobs/upload c’est message: "rate limit exceeded" (sans details). |
5xx | erreur interne du service ; réessayez avec un backoff exponentiel |
Pour distinguer les trois cas de 429 : quota — par la présence de QuotaExceededDetail ; concurrence — par la sous-chaîne too many concurrent jobs ; débit — par la sous-chaîne grpc_ratelimit / rate limit exceeded.
Les erreurs au sein d’un job (l’échec du traitement d’un seul fichier) ne sont pas renvoyées sous forme de code HTTP — elles figurent dans le résultat du job au niveau du fichier, et le statut du job devient JOB_STATUS_PARTIAL (si au moins un fichier a obtenu une réponse de modèle réussie) ou JOB_STATUS_FAILED (si aucun ne l’a obtenue).
Les problèmes de l’étape OCR se manifestent comme des marqueurs au niveau du job (pas des erreurs HTTP à la création) ; la façon dont le job se termine dépend du problème : Marqueurs d’authentification/configuration qui font échouer le job entier : provider_auth_failed, provider_key_required, provider_required, model_required, unsupported_provider. Marqueurs permanents au niveau du fichier (ces fichiers échouent, le job peut se terminer en JOB_STATUS_PARTIAL) : too_many_pages, unsupported_request, file_too_large, unsupported_format. Les problèmes transitoires du backend sont réessayés en interne et n’entraînent pas l’échec du job : rate_limited, ocr_backend_overloaded, ocr_backend_error, ocr_backend_unavailable, ocr_timeout. Les erreurs de validation à la création (ocr.provider manquant, ocr.model vide ou ocr.providerKey vide) → 400 avant le début du traitement.