Guide

Gestion des erreurs

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

{
  "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 :

TypeSignification
authentication_errorUn problème lié à la manière dont vous avez authentifié la requête (ou si vous l'avez fait).
invalid_request_errorLa requête elle-même est mal formée — un paramètre manquant ou invalide.
not_found_errorLa 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_creditsVotre compte ne dispose pas de suffisamment de crédits pour effectuer l'action (payante) demandée.
rate_limit_errorVous avez dépassé la limite de requêtes pour cette catégorie d'endpoint — voir Limites de débit.
internal_errorUne 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 <clé>.

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 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.

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.

📮 contact email: [email protected]