# Gestion des erreurs de l'API — Types d'erreur, codes et doc_url > Chaque erreur v1 est un objet JSON contenant type, code, message et doc_url — cette page documente la taxonomie complète des types d'erreur et chaque code d'erreur individuel, et correspond exactement à la page vers laquelle un doc_url renvoyé redirige. Toute requête v1 échouée — toute réponse non-2xx — renvoie la même structure JSON, détaillée ci-dessous. Cette page est également celle vers laquelle chaque `doc_url` d'erreur redirige : chaque code possède sa propre section ancrée, donc suivre un `doc_url` depuis une réponse d'erreur réelle vous mène directement à l'explication de ce code précis. ## Structure de l'erreur ```json { "error": { "type": "invalid_request_error", "code": "missing_parameter", "message": "A required parameter is missing.", "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter", "param": "file" } } ``` - `type` — la catégorie générale de cette erreur (voir le tableau ci-dessous). Utile pour une ramification grossière dans votre code de gestion d'erreurs (« est-ce un problème d'authentification ou de validation ») sans vérifier chaque `code` individuellement. - `code` — l'identifiant d'erreur spécifique et stable. C'est ce que vous devez utiliser dans votre code — il ne changera pas même si le libellé du `message` est amélioré ultérieurement. - `message` — une explication lisible par un humain. Utile pour les logs et le débogage, non destiné à être analysé. - `doc_url` — un lien direct vers la section de cette page pour ce `code` précis. - `param` — présent uniquement sur les erreurs de type validation (`missing_parameter`, `invalid_parameter`, `duplicate_field_name`), nommant le champ de requête spécifique qui a provoqué l'erreur. Omis entièrement — pas `null` — lorsqu'il n'est pas applicable. ## Types d'erreurs Chaque `code` appartient à un seul `type` : | Type | Signification | | --- | --- | | authentication_error | Un problème lié à la manière dont vous avez authentifié la requête (ou si vous l'avez fait). | | invalid_request_error | La requête elle-même est mal formée — un paramètre manquant ou invalide. | | not_found_error | La ressource référencée dans l'URL (un document, un lot ou un ID de modèle) n'existe pas ou n'appartient pas à votre compte. | | insufficient_credits | Votre compte ne dispose pas de suffisamment de crédits pour effectuer l'action (payante) demandée. | | rate_limit_error | Vous avez dépassé la limite de requêtes pour cette catégorie d'endpoint — voir Limites de débit . | | internal_error | Une erreur s'est produite de notre côté, pas du vôtre. | ## Un cas particulier : `processing_error` `processing_error` n'est **pas** un `type` que vous verrez jamais dans une réponse `{"error": ...}` de premier niveau. Il ne provoque jamais l'échec d'un appel API en lui-même. Au lieu de cela, il décrit un document individuel au sein d'un lot qui n'a pas pu être extrait — vous le verrez reflété comme `"status": "failed"` sur ce document dans une réponse `GET /batches/{batch_name}/results` par ailleurs 200 OK, aux côtés d'autres documents du même lot qui ont réussi. Ne traitez pas un échec au niveau d'un document au sein d'un appel API réussi comme une erreur justifiant de réessayer l'ensemble du lot — vérifiez le `status` propre à chaque document. ## Codes d'erreur ### missing_api_key **Type :** `authentication_error` · **Code HTTP :** 401 Aucune clé API fournie. Envoyez-la sous la forme `Authorization: Bearer `. ### invalid_api_key **Type :** `authentication_error` · **Code HTTP :** 401 La clé API fournie est invalide, ou le compte auquel elle appartient est désactivé. ### plan_required **Type :** `authentication_error` · **Code HTTP :** 403 L'API n'est pas disponible avec le plan Free. Passez à Basic ou supérieur pour l'utiliser. ### missing_parameter **Type :** `invalid_request_error` · **Code HTTP :** 400 Un paramètre obligatoire est manquant. Consultez `param` dans l'objet d'erreur pour savoir lequel. ### invalid_parameter **Type :** `invalid_request_error` · **Code HTTP :** 400 Un paramètre a une valeur invalide. Consultez `param` et `message` pour les détails — ce code générique couvre tout, d'une chaîne `crop` malformée à une valeur `limit` hors limites, en passant par un lot ne contenant aucun élément éligible au traitement. ### duplicate_field_name **Type :** `invalid_request_error` · **Code HTTP :** 400 Un champ portant ce nom existe déjà sur ce modèle. Les noms de champs doivent être uniques au sein d'un modèle. ### idempotency_key_reused **Type :** `invalid_request_error` · **Code HTTP :** 400 Cette `Idempotency-Key` a déjà été utilisée pour une requête avec des paramètres différents. Utilisez une nouvelle clé pour une requête réellement différente — consultez la section [Idempotence](/developers/guides/idempotency) pour le comportement complet. ### document_not_found **Type :** `not_found_error` · **Code HTTP :** 404 Aucun document trouvé avec cet identifiant (soit il n'existe pas, soit il n'appartient pas à votre compte). ### batch_not_found **Type :** `not_found_error` · **Code HTTP :** 404 Aucun lot trouvé avec ce nom. ### template_not_found **Type :** `not_found_error` · **Code HTTP :** 404 Aucun modèle trouvé avec cet identifiant. ### insufficient_credits **Type :** `insufficient_credits` · **Code HTTP :** 402 Crédits insuffisants pour effectuer cette action. Consultez `GET /account` pour connaître votre solde `available_credits` avant de réessayer. ### rate_limit_exceeded **Type :** `rate_limit_error` · **Code HTTP :** 429 Trop de requêtes. Ralentissez et réessayez après la réinitialisation de la fenêtre — consultez l'en-tête de réponse `X-RateLimit-Reset` et le guide [Limites de débit](/developers/guides/rate-limits). ### internal_error **Type :** `internal_error` · **Code HTTP :** 500 Une erreur inattendue s'est produite. Si elle persiste, c'est de notre côté, pas du vôtre — si vous pouvez la reproduire de manière fiable, ces informations sont utiles à inclure si vous nous contactez à ce sujet. --- Source: https://imagetotable.ai/fr/developers/guides/errors