Erreurs et nouvelles tentatives

Ces guides concernent les API texte et tableaux. Consultez chaque référence pour les entrées, formats et erreurs spécifiques.

Réponses d’erreur

Exemple de réponse d’erreur JSON :

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "error": {
    "code": "insufficient_balance",
    "message": "Recognition did not complete",
    "required_reservation_usd": "0.011288000"
  }
}

Codes d’état HTTP

HTTP	error.code
400	invalid_request, invalid_idempotency_key, invalid_image
401	unauthorized
402	insufficient_balance
403	account_unavailable
405	invalid_request
409	idempotency_conflict, request_in_progress
413	image_too_large, input_limit_exceeded
415	unsupported_media_type
422	recognition_blocked
429	rate_limit_exceeded, concurrency_limit_exceeded
502	recognition_failed, output_truncated, empty_result, invalid_usage
503	service_unavailable, settlement_pending, export_failed
504	request_timeout

HTTP	Cause	Action recommandée
400 / 413 / 415	Requête, taille ou format d’image non valide	Corriger le fichier ou réduire sa taille
405	Méthode HTTP incorrecte	Utiliser POST
401	Clé API absente ou invalide	Vérifier la clé Bearer
403	Compte indisponible	Vérifier le compte ou lever la restriction
402	Solde disponible insuffisant	Recharger, puis consulter error.required_reservation_usd et les réservations de solde
409	Conflit d’idempotence ou opération en cours	Si request_in_progress, conserver l’identifiant et l’image puis réessayer après attente ; en cas de conflit, corriger l’identifiant
429	Limite de débit ou de concurrence	Attendre selon Retry-After
422 / 502 confirmé	Échec de reconnaissance confirmé	Pas de facturation de reconnaissance ; examiner l’erreur
503 / 504 / résultat incertain	État du service, du règlement ou délai incertain	Ne pas supposer l’absence de débit ; réessayer avec le même Idempotency-Key et l’image

Les erreurs sont renvoyées en JSON avec request_id, error.code et error.message. Toutes les réponses utilisent Cache-Control: no-store. La reconnaissance n’est pas diffusée en continu : les succès utilisent le format choisi et les erreurs restent en JSON. Conservez X-Request-Id pour le support.

Idempotence

Idempotency-Key identifie l’opération : 16–128 lettres ASCII, chiffres ou . _ : -. Nouvelle image : nouvel identifiant unique. Nouvelle tentative : même identifiant, mêmes octets originaux et MIME. La portée est le compte, même si la clé API change. Dans les 24 heures après acceptation, une opération terminée renvoie request_id, résultat et coût initiaux avec Idempotency-Replayed: true, sans nouvelle génération ni facturation.

Utilisez un Idempotency-Key différent pour chaque nouvelle opération ou point d’accès. Le partager entre texte et tableaux renvoie 409 idempotency_conflict. Pour changer le format de la même opération, conservez la clé et l’image d’origine.

Stratégie de nouvelle tentative

En cas d’erreur réseau, request_in_progress ou settlement_pending, conservez identifiant et image, attendez Retry-After secondes puis réessayez. Ne créez pas une autre opération si le règlement est incertain. Les échecs terminaux sauvegardés renvoient la même erreur ; changez d’identifiant seulement après échec confirmé pour recommencer volontairement. Après 24 heures, un identifiant peut créer une nouvelle opération payante ; une récupération non terminée bloque encore sa réutilisation.

Sécurité de la facturation

Un échec de reconnaissance confirmé n’est pas facturé, mais une réponse perdue ou settlement_pending peut correspondre à un débit déjà effectué ou à une réserve conservée. Tant que le résultat reste incertain, ne créez pas une autre opération avec un nouvel Idempotency-Key ; réessayez avec l’identifiant et l’image d’origine et conservez X-Request-Id pour le support.