Codes d'erreur de l'API

Référence complète de tous les codes d'erreur que l'API peut retourner, avec le status HTTP, quand ils surviennent et comment récupérer.

Enveloppe d'erreur

Chaque réponse d'erreur utilise la même structure JSON canonique :

JSON
{
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File is too large. Maximum size is 200 MB.",
    "details": { "max_bytes": 209715200, "received_bytes": 240000000 }
  }
}

Vérifiez toujours aussi le status code HTTP — il indique la catégorie générale (4xx = erreur client, 5xx = erreur serveur).

Référence des codes d'erreur

CodeHTTPQuandComment récupérer
NO_FILE 400 Vous avez oublié d'attacher un champ file, ou l'upload multipart était mal formé. Envoyez la requête en multipart/form-data avec un champ file. Pour les endpoints batch, utilisez files[].
INVALID_FORMAT 400 Vous avez oublié to_format, ou la conversion demandée n'est pas prise en charge (par ex. jpg → zzz). Transmettez un to_format valide. Consultez la référence convert pour la liste complète des formats pris en charge.
FILE_TOO_LARGE 413 Le fichier envoyé dépasse la limite de taille (200 Mo par défaut, plus basse pour certains outils IA). Redimensionnez/compressez le fichier avant l'envoi, ou découpez-le en plus petits morceaux.
UNSUPPORTED_MIME 415 Le type MIME du fichier n'est pas dans notre liste blanche (par ex. .exe, .zip quand non attendu). Vérifiez le format de votre fichier. Consultez les formats pris en charge sur la page d'accueil.
RATE_LIMITED 429 Vous avez atteint l'une des 5 limites de rate limit. Respectez l'en-tête Retry-After. Voir les limites de débit.
JOB_NOT_FOUND 404 Le job_id n'existe pas (faute de frappe, jamais créé), ou il a expiré (les jobs sont conservés 2 heures). Vérifiez que le job_id comporte exactement 32 caractères hexadécimaux et a été créé dans les 2 dernières heures.
JOB_EXPIRED 410 Le job a plus de 2 heures et le fichier converti a été supprimé automatiquement. Relancez la conversion. Téléchargez toujours le résultat rapidement après la fin du job.
CONVERSION_FAILED 500 Le moteur de conversion s'est exécuté mais a échoué (par ex. source corrompue, dépendances manquantes, exception interne). Consultez error.message pour les détails. Essayez un autre fichier. Signalez les échecs répétés via /contact.
BATCH_TOO_LARGE 400 Votre requête POST /api/v1/batch contenait plus de 20 fichiers. Divisez votre batch en lots de ≤20 fichiers.
NOT_FOUND 404 Endpoint inconnu ou slug d'outil inconnu (par ex. /api/v1/tools/foobar). Vérifiez l'orthographe. Consultez /api/reference pour les endpoints valides.
NOT_IMPLEMENTED 501 L'endpoint existe dans notre documentation mais n'est pas encore implémenté côté serveur (par ex. flip-image). Utilisez une solution de contournement (par ex. /api/v1/convert avec img_rotate=flip-h) ou attendez la mise en ligne de la fonctionnalité.
BANNED 403 Votre IP a déclenché plus de 10 refus de rate limit en 1 heure et est maintenant bannie pour 24 heures. Attendez l'expiration du bannissement (voir Retry-After). Si l'IP est partagée, contactez-nous via /contact.
INTERNAL_ERROR 500 Échec inattendu côté serveur. Devrait être rare. Réessayez une fois après quelques secondes. Si cela persiste, signalez via /contact avec l'en-tête X-Request-Id de la réponse.

L'en-tête X-Request-Id

Chaque réponse de l'API (succès ou erreur) inclut un en-tête X-Request-Id. Lorsque vous signalez un problème, veuillez inclure cet ID pour que nous puissions retrouver la requête dans nos logs :

HTTP headers
X-Request-Id: 4f2dc3b5cc79fa57

Demander une fonctionnalité

0 / 2000