OCR Platform
Admin

URL base API

https://ocr.789.com.mx/v1

Errores comunes

Errores HTTP frecuentes

HTTP Código Causa Acción
401 invalid_api_key Falta o incorrecta X-API-Key Verifica header y valor
403 api_key_not_active Key suspendida, revocada o expirada, o proyecto/ambiente inactivo Solicita nueva key al equipo interno
403 insufficient_scope Scope insuficiente Pide ampliación de scopes
404 document_not_found ID inexistente o de otra key Usa el document_id de tu respuesta POST
404 extraction_not_found ID inexistente o de otra key Usa el id de tu respuesta POST /extractions
404 result_not_available Documento failed, cancelled, expired o purged, o format que no pediste al crear Pide un formato de output_formats; si expiró, sube el documento de nuevo
404 extraction_result_not_available La extracción está completed pero su resultado no existe Reporta el request_id al equipo de plataforma
409 result_not_ready Documento o extracción aún en proceso Sigue haciendo polling del estado
409 document_cannot_be_cancelled El documento ya salió de queued Solo se cancela antes de enviarse a OCR
409 document_not_extractable Documento failed, cancelled, expired o purged; o terminado sin el input_result_type pedido Usa un documento completed o partial_success y pide un input_result_type que haya generado (o omítelo para que se elija solo)
409 idempotency_conflict Misma Idempotency-Key con payload distinto Usa key nueva o repite payload original
413 file_too_large El archivo supera el tamaño máximo Reduce el archivo (50 MB en los perfiles actuales)
413 result_not_available Resultado OCR mayor a 512 KB inline Pídelo con download=true
415 unsupported_media_type Tipo de archivo no permitido o extensión que no coincide con el contenido Envía PDF, JPEG, PNG, HEIC/HEIF, TXT o XML con su extensión real
422 validation_error Campos inválidos, Idempotency-Key ausente o corta, response_schema inválido o documento con más páginas de las permitidas Revisa error.details en la respuesta
429 rate_limit_exceeded Más de 120 peticiones por minuto con la misma key Espera lo que indica el header Retry-After

Problemas operativos

Documento failed tras estar en queued o processing

La API procesa en background. Si un documento se atasca, la plataforma lo marca failed automáticamente con un failure.code (document_queue_timeout, docling_submit_timeout, docling_processing_timeout o docling_polling_stalled). No necesitas escalar mientras el estado siga avanzando; si ves estos códigos de forma repetida, reporta el meta.request_id. Lista completa en Flujo: documento OCR.

"The file failed to upload..." al subir

  • El archivo no se adjuntó correctamente: usa multipart/form-data con el campo file de tipo File (en Postman, no Text).
  • El archivo supera el límite de tamaño del servidor.

422 con "The response_schema is invalid."

error.details.response_schema lista los problemas. Los más comunes:

  • Root schema type must be object. — usaste el formato abreviado ("total": "number|null") o la raíz no es "type": "object".
  • Schema contains unsupported keywords or types. — usaste format, pattern, minimum u otra keyword no soportada.

Ver la sección "Errores y cómo corregirlos" en la Guía de prompts y schemas.

Extracción en waiting_for_document mucho tiempo

El documento OCR aún no terminó. Consulta GET /documents/{id}. Si el documento termina en failed, la extracción pasa sola a failed con extraction_input_unavailable.

Extracción validation_failed

El LLM devolvió JSON que no cumple response_schema en ningún intento. GET /extractions/{id} incluye failure.validation_errors con el detalle del último intento, por ejemplo $.total: value does not match expected type.. Ajusta instrucción o schema y crea una nueva extracción (nueva Idempotency-Key).

Extracción failed

Revisa failure.code en GET /extractions/{id}; la tabla completa de códigos está en Flujo: extracción.

Extracción failed con extraction_input_unavailable

El documento no tiene el formato OCR pedido o el contenido supera el límite que se envía al modelo. Prueba otro input_result_type (text suele ser el más compacto).

Formato de error

{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid fields.",
    "details": {
      "file": ["The file field is required."]
    }
  },
  "meta": {
    "request_id": "req_..."
  }
}

Usa meta.request_id al reportar incidentes al equipo de soporte.