Trata un resultado de conversión como un trabajo con estado, no como una descarga de archivo síncrona. Así tu producto será fiable cuando los archivos de origen sean grandes, no estén disponibles o tengan un formato incorrecto.
Reintenta de forma segura
Reintenta únicamente las solicitudes que puedan repetirse de forma segura. Una solicitud de resultado se puede reintentar con espera exponencial. Para solicitudes de envío, conserva el ID de tarea devuelto por una respuesta correcta antes de intentar otro envío.
Gestiona errores finales
Cuando una tarea tenga el estado failed, registra su ID y el motivo devuelto junto con tu ID interno de trabajo. Muestra a los usuarios un siguiente paso práctico, como comprobar la URL de origen o subir un PDF legible, en lugar de exponer un error de API sin formato.
Define límites de tiempo prácticos
Usa una fecha límite de consulta que se ajuste a la experiencia de tu producto. Detén la consulta cuando se alcance ese límite, conserva el ID de tarea y deja que un proceso en segundo plano o una actualización iniciada por el usuario compruebe el estado final más tarde.
Consulta la Referencia de la API para ver campos de respuesta y ejemplos de errores exactos.