Codes d'erreur de l'API EnConvert#

Cette référence répertorie tous les codes de statut HTTP et messages d'erreur renvoyés par l'API EnConvert, de 200 OK pour les conversions synchrones et 202 Accepted pour les tâches async et batch, jusqu'aux réponses d'erreur documentées ci-dessous. Chaque section d'erreur liste les chaînes de message exactes, la condition qui déclenche chacune d'elles, et comment corriger la requête. Les corps d'erreur n'ont pas tous la même forme : il en existe six, et la section Format des réponses d'erreur les présente toutes.

Une tâche qui échoue après avoir été acceptée n'est pas une erreur HTTP. Le 202 reste valable et l'échec apparaît dans la charge utile de statut de la tâche lorsque vous l'interrogez, comme décrit dans Tâches synchrones et asynchrones.

Codes de statut HTTP#

Format des réponses d'erreur#

Il existe six formes de corps. Celle que vous recevez dépend de l'endroit où la défaillance s'est produite, pas du seul code de statut : vérifiez le type de detail avant de le lire.

1. detail sous forme de chaîne. Le cas courant, et la seule forme que voient la plupart des intégrations.

{
    "detail": "Authentication required"
}

2. detail sous forme d'objet. Le 413 de taille de fichier lié au plan. L'objet structuré est la valeur de detail : lisez body.detail.max_size, pas body.max_size. Voir 413 Payload Too Large.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

3. detail sous forme de tableau, plus errors. La validation de schéma (422) renvoie les deux : detail est la sortie brute du validateur, errors est un tableau parallèle de chaînes lisibles par un humain. Voir 422 Unprocessable Entity.

4. Enveloppe de conversion typée. {"error", "code", "detail"}, avec un code lisible par une machine. Émise uniquement par les trois endpoints de conversion d'URL V1. Voir Erreurs de conversion navigateur.

5. Exception non gérée. Un 500 qui ne provient pas d'un convertisseur n'a aucun detail :

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

6. Délai de requête de la passerelle. Le budget propre de 300 secondes de la passerelle produit un 504 sans detail ni code :

{
    "error": "Request timeout"
}

400 Bad Request#

Renvoyé lorsque la requête contient des paramètres invalides, des champs manquants ou des données mal formées.

Validation des entrées#

Validation du lot et du mode#

Validation de l'authentification, des cookies et des en-têtes#

Sécurité des URL (SSRF)#

Chaque endpoint basé sur une URL examine l'url cible avant de la récupérer. Ces messages sont renvoyés en 400 lorsque l'URL n'est pas une adresse publique http(s).

Validation des options de rendu#

Erreurs de sitemap et de crawl#

Erreurs de contenu de conversion#

401 Unauthorized#

Renvoyé lorsque l'authentification est manquante ou invalide.

402 Payment Required#

Renvoyé lorsqu'une limite d'utilisation est dépassée. La répartition entre 402 et 403 n'est pas symétrique, et elle prend souvent les développeurs de court. Toute condition de quota répond 402, tout comme un endpoint V2 désactivé sur votre plan. Les restrictions de fonctionnalités V1 répondent 403 (async, webhooks, sortie ZIP, authentification de base, lot). La limitation de débit est un mécanisme distinct qui répond 429, jamais 402.

L'épuisement des crédits IA mensuels ne produit pas de 402. L'extraction de schéma se rabat sur le résultat heuristique et CSS, et la requête aboutit quand même. Les allocations, les tarifs et ce qui compte pour une opération figurent dans Limites de débit et quotas.

403 Forbidden#

Renvoyé lorsque l'accès est refusé en raison de restrictions liées au type de clé, au domaine, à une fonctionnalité de plan V1 ou à l'endpoint. Les restrictions d'endpoints V2 font exception : elles répondent 402, pas 403.

Restrictions de clé API et de jeton#

Restrictions de fonctionnalités du plan#

Restrictions de widget#

Deux autres messages 403 ne concernent ni les clés ni les plans : Account suspended, renvoyé pour chaque requête dès que le compte derrière la clé ou le jeton est suspendu, et robots.txt disallows fetching this URL (request sent respect_robots=true)., renvoyé par perceive lorsque vous avez demandé le respect de robots et que la cible interdit ce chemin.

404 Not Found#

409 Conflict#

410 Gone#

L'artefact a existé, mais il a dépassé la fenêtre de rétention de fichiers de votre plan et n'est plus dans le stockage. La rétention dépend du plan ; voir Limites de débit et quotas.

Considérez 410 comme définitif pour cet objet. Relancer la requête produit un nouvel artefact ; réessayer le téléchargement n'y changera rien.

413 Payload Too Large#

Renvoyé lorsque le fichier téléversé dépasse la taille de fichier maximale du plan.

{
    "detail": {
        "error": "File too large",
        "file_size": 10485760,
        "max_size": 5242880,
        "tier": "free",
        "key_type": "private"
    }
}

La limite est vérifiée sur le nombre exact d'octets de la partie téléversée, avant tout début de travail de conversion. Un fichier dont la taille vaut exactement max_size est accepté ; seul un fichier plus grand est rejeté. L'en-tête Content-Length sert de repli pour les anciens points d'appel qui ne transmettent pas leur objet d'upload à la vérification.

POST /v2/ingest/files n'utilise pas cette forme. Il répond 413 avec un detail sous forme de simple chaîne : File '{filename}' exceeds the {max_size}-byte limit.

Les plafonds par plan sont listés dans Limites de débit et quotas, et les chemins d'upload concernés dans Ingestion de fichiers.

Erreurs de conversion navigateur (415 / 422 / 502 / 504)#

Les conversions d'URL distinguent une défaillance du site cible ou de l'entrée (un 4xx, 502 ou 504 sur lequel vous pouvez agir) d'une défaillance de notre moteur (un 500). Les trois endpoints de conversion d'URL V1 (url-to-pdf, url-to-screenshot, url-to-markdown) renvoient ces échecs typés avec un code lisible par une machine à côté de detail :

{
    "error": "Gateway Timeout",
    "code": "upstream_timeout",
    "detail": "The target site took too long to respond while rendering PDF for https://example.com."
}

Ces cinq valeurs constituent tout le vocabulaire. Aucune autre famille d'endpoints n'émet de code, V2 comprise : un échec V2 revient sous forme de simple chaîne detail. La classe de base de l'enveloppe définit un sixième slug, conversion_error, mais rien ne le déclenche, donc il ne vous parvient jamais. Branchez votre code sur les cinq valeurs ci-dessus et traitez toute autre valeur comme inconnue.

Un 504 peut aussi arriver sous deux formes non typées : {"error": "Request timeout"} lorsque la requête dépasse le budget de 300 secondes de la passerelle, et un detail sous forme de simple chaîne portant le message de délai lorsqu'une conversion de document (LibreOffice) expire. Ni l'une ni l'autre ne porte de code.

422 Unprocessable Entity#

Les échecs de validation de schéma renvoient deux tableaux parallèles. detail est la sortie brute du validateur, c'est ce que vous remappez sur vos champs de formulaire. errors contient une chaîne lisible par un humain par problème, c'est ce que vous affichez à l'utilisateur.

{
    "detail": [
        {
            "loc": ["body", "max_pages"],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "type": "int_parsing"
        }
    ],
    "errors": [
        "body.max_pages: Input should be a valid integer, unable to parse string as an integer (you sent 'ten')"
    ]
}

Trois valeurs de type méritent d'être traitées nommément :

Un 422 accompagné du code selector_not_found est autre chose : une précondition de rendu qui a échoué, traitée dans Erreurs de conversion navigateur.

429 Too Many Requests#

La limitation de débit est un contrôle d'équité sur une courte fenêtre, distinct du quota mensuel d'ops. L'épuisement du quota répond 402 ; seul le limiteur de débit répond 429.

Un 429 porte quatre en-têtes :

Ces en-têtes n'apparaissent que sur le 429. Les réponses réussies ne portent aucun en-tête de limite de débit ni d'ops restantes : vous ne pouvez donc pas lire votre budget restant sur une réponse, consultez votre utilisation dans le tableau de bord. Voir Limites de débit et quotas.

500 Internal Server Error#

Toute défaillance survenant en dehors d'un convertisseur ne vous parvient jamais sous forme de texte. Elle revient sans aucun detail :

{
    "error": "Internal server error",
    "event_id": "a1b2c3d4"
}

Un cas surprend souvent : un corps JSON mal formé envoyé à un endpoint d'URL V1 (url-to-pdf, url-to-screenshot, url-to-markdown, website-to-pdf, website-to-screenshot) renvoie ce 500 plutôt qu'un 422, car ces endpoints lisent le corps brut. Le même corps mal formé sur un endpoint V2 renvoie un 422 avec type: json_invalid.

Si vous rencontrez des erreurs 500 persistantes, le problème vient probablement du fichier ou de l'URL d'entrée. Essayez avec une entrée différente pour isoler le problème.

503 Service Unavailable#

Deux portillons de capacité distincts existent et ils demandent des attentes différentes : lisez Retry-After plutôt que d'en supposer une. Ces erreurs sont par ailleurs transitoires, réessayez après un court délai.

Erreurs des endpoints V2#

Les endpoints d'intelligence web V2 réutilisent les codes de statut ci-dessus, avec quelques conditions spécifiques à la V2 qui méritent d'être signalées.

Quota et plan (402 / 403)#

Les opérations V2 sont décomptées sur le même quota mensuel unifié d'ops que les conversions V1 : une op par unité de travail. N'importe quel plan payant avec dépassement activé ($0.02/op) permet d'aller au-delà de l'allocation ; sinon, la limite est stricte.

Deux comportements V2 ne sont délibérément pas des erreurs. L'épuisement du solde de crédits IA ne fait pas échouer la requête : l'extraction de schéma se rabat sur le résultat heuristique et CSS. Et une exécution distill multi-URL qui franchit la limite d'ops en cours de route ne renvoie pas non plus de 402 : elle s'arrête là, renvoie les URL qu'elle a terminées et ajoute un avertissement indiquant combien ont été ignorées.

Validation (422)#

Chaque schéma de requête V2 rejette les clés inconnues : un paramètre mal orthographié devient un 422 qui nomme le champ. La forme du corps est décrite dans 422 Unprocessable Entity.

Fournisseur de recherche (502 / 503)#

L'endpoint lookup dépend d'un fournisseur de recherche en amont. Le texte d'erreur brut du fournisseur n'atteint jamais le client.

Non trouvé (404)#

GET et DELETE sur un operation_id, job_id ou watcher_id V2 qui n'existe pas, ou qui appartient à un autre projet, renvoient 404. L'existence n'est jamais divulguée entre projets.

Accepté (202)#

Ingest est toujours asynchrone : POST /v2/ingest répond 202 avec un job_id que vous interrogez. Les lots perceive de plus de 10 URL répondent 202 avec le statut queued. Un lot de 10 URL ou moins répond normalement en ligne, mais s'il dépasse la fenêtre en ligne il bascule en 202 avec le statut processing et un avertissement : gérez donc 202 quelle que soit la taille du lot.

Un 202 signifie aussi que les échecs ultérieurs ne sont pas des erreurs HTTP. Interrogez la tâche et lisez sa charge utile de statut, comme décrit dans Tâches synchrones et asynchrones.

Dépannage#

Problèmes d'authentification#

• Vous obtenez un 401 ? Vérifiez que votre clé API est valide et active dans le tableau de bord. Si vous utilisez un JWT, assurez-vous que le jeton n'a pas expiré (durée de vie d'1 heure).
• Vous obtenez un 403 concernant l'utilisation depuis un navigateur ? Vous utilisez une clé privée (sk_...) depuis du code côté client. Passez à une clé publique avec JWT pour les requêtes basées sur un navigateur.
• Vous obtenez un 403 concernant le domaine ? Ajoutez votre domaine à la liste des domaines autorisés de la clé API dans le tableau de bord.

Problèmes de conversion#

• Vous obtenez un 400 concernant le format de fichier ? Assurez-vous que l'extension du fichier téléversé correspond à l'endpoint (par ex. .json pour json-to-xml, .docx pour doc-to-pdf).
• Vous obtenez un 413 ? Votre fichier dépasse la limite de taille du plan. Lisez detail.max_size dans la réponse, puis vérifiez la taille de fichier maximale de votre plan ou passez à un plan supérieur.
• Vous obtenez un 402 ? Vous avez atteint votre quota mensuel d'ops, le plafond de watchers ou la limite de stockage, ou bien le projet n'a aucune période de facturation active. Vérifiez votre utilisation dans le tableau de bord et consultez Limites de débit et quotas.

Problèmes d'accès aux fonctionnalités#

• Vous obtenez un 403 concernant les fonctionnalités du plan ? La fonctionnalité V1 que vous essayez d'utiliser (async, lot, webhooks, sortie ZIP, authentification de base) nécessite un niveau de plan supérieur. Consultez le tableau de restriction des fonctionnalités.
• Vous obtenez un 402 sur un endpoint V2 qui n'a rien à voir avec le quota ? Les restrictions d'endpoints V2 répondent 402, pas 403. Le message est ... is not available on your current plan. Upgrade to a V2-inclusive plan to access this endpoint.

Questions fréquentes#

Pourquoi l'API renvoie-t-elle 402 Payment Required pour une conversion de fichier ?#

Une 402 signifie qu'une limite d'utilisation est épuisée : votre quota mensuel unifié d'ops (500 ops sur le plan Founding), le plafond de watchers actifs, ou l'allocation de stockage de votre projet. Elle couvre aussi deux cas hors quota : un projet sans période de facturation active, et un endpoint V2 désactivé sur votre plan. Les requêtes en lot qui dépasseraient le quota mensuel d'ops restant sont rejetées d'emblée avec une 402 pour le lot entier. Les conversions V1 et les opérations V2 puisent dans le même quota ; n'importe quel plan payant avec dépassement activé ($0.02/op) permet d'aller au-delà. La limitation de débit est un mécanisme différent et répond 429.

Comment corriger une erreur 401 Unauthorized de l'API de conversion ?#

Vérifiez que la clé API est présente, commence par sk_ ou pk_, et est toujours active dans le tableau de bord, car les clés révoquées renvoient API Key revoked. Si vous vous authentifiez avec un JWT, notez que les jetons d'accès expirent après 1 heure (Token has expired) et les jetons de rafraîchissement après 7 jours.

Pourquoi est-ce que j'obtiens 413 Payload Too Large lors de l'envoi d'un fichier ?#

Le fichier téléversé dépasse la taille de fichier maximale de votre plan, mesurée sur le nombre exact d'octets de la partie téléversée avant tout début de travail de conversion. Un fichier exactement à la limite est accepté. Le corps du 413 imbrique un objet structuré sous detail, avec file_size, max_size (tous deux en octets), tier et key_type : lisez-le donc comme detail.max_size et non comme un champ de premier niveau.

Puis-je utiliser une clé API privée depuis du JavaScript navigateur ?#

Non. Une clé privée (sk_...) utilisée dans une requête comportant un en-tête Origin de navigateur renvoie 403 Private API keys cannot be used from browsers. Échangez une clé publique contre un JWT sur /v1/auth/token et utilisez ce jeton pour les appels API depuis un navigateur.

Une erreur 503 Service Unavailable de l'API est-elle permanente ?#

Non, les erreurs 503 telles que Converter not available: {endpoint} ou Turnstile verification unavailable sont généralement transitoires. Réessayez la requête après un court délai.