Errores y reintentos

Estas guías se aplican a Imagen a texto e Imagen a tabla. Consulta las entradas, formatos y errores específicos en la referencia de cada API.

Respuestas de error

Ejemplo de error JSON:

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

Códigos de estado 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	Causa	Qué hacer
400 / 413 / 415	Solicitud, tamaño o formato de imagen no válidos	Corrige el archivo o reduce el tamaño
405	Método HTTP incorrecto	Usa POST
401	Clave API ausente o inválida	Revisa la clave Bearer
403	Cuenta no disponible	Verifica la cuenta o resuelve la restricción
402	Saldo disponible insuficiente	Recarga; revisa error.required_reservation_usd y las reservas de saldo
409	Conflicto de idempotencia u operación en curso	Si es request_in_progress, conserva ID e imagen y reintenta tras esperar; si hay conflicto, corrige el ID de operación
429	Límite de solicitudes o concurrencia	Espera según Retry-After
422 / 502 confirmado	Fallo confirmado de reconocimiento	No hay cargo por reconocimiento; revisa el error
503 / 504 / incierto	Estado del servicio, liquidación o tiempo incierto	No supongas que no hay cargo; reintenta con el mismo Idempotency-Key e imagen

Los errores se devuelven en JSON con request_id, error.code y error.message. Todas las respuestas incluyen Cache-Control: no-store. El reconocimiento no usa streaming: las respuestas correctas tienen el formato elegido y los errores siguen siendo JSON. Guarda X-Request-Id para soporte.

Idempotencia

Idempotency-Key identifica la operación: 16–128 letras ASCII, dígitos o . _ : -. Para una nueva imagen usa un ID único nuevo; al reintentar conserva ID, bytes originales y MIME. El ámbito es la cuenta, incluso al cambiar de clave API. Durante 24 horas desde la aceptación, las operaciones terminadas devuelven request_id, resultado y cargo originales con Idempotency-Replayed: true, sin generar ni cobrar otra vez.

Usa un Idempotency-Key distinto para cada operación o endpoint nuevo. Compartirlo entre texto y tablas devuelve 409 idempotency_conflict. Para cambiar el formato de una misma operación, reutiliza la clave y la imagen originales.

Estrategia de reintento

Ante errores de red, request_in_progress o settlement_pending, conserva ID e imagen, espera Retry-After segundos y reintenta. No crees otra operación con liquidación incierta. Los fallos finales guardados repiten el error; usa otro ID solo tras confirmar el fallo y querer empezar de nuevo. Pasadas 24 horas el ID puede iniciar otra operación cobrada; una recuperación pendiente sigue bloqueando su reutilización.

Seguridad de la facturación

Un fallo confirmado de reconocimiento no se cobra. Sin embargo, una respuesta perdida o settlement_pending puede indicar que ya se liquidó el cargo o que sigue habiendo una reserva. No inicies otra operación con un Idempotency-Key nuevo si el resultado sigue incierto; conserva el ID y la imagen, y guarda X-Request-Id para soporte.