Si la interfaz informa un error, ¿intentar de nuevo? Las tareas de documentación primero deben distinguir qué fallas se pueden recuperar.

Puntos clave de este artículo

Después de que la interfaz informa un error, no se puede volver a intentarlo todo el tiempo. Primero debe manejarse por separado según la categoría de falla.
Es posible que el servidor ya haya creado una tarea cuando se agote el tiempo de espera de POST. El reenvío ciego sin claves idempotentes o mecanismos de consulta producirá tareas duplicadas.
En el ejemplo, solo las fallas temporales están limitadas por 1, 2 y 4 segundos para retroceder. Si se excede el número de veces, se detendrá y no deberá volver a intentarse indefinidamente.
Los permisos no válidos, los atrasos en la cuenta y los errores de entrada deberían solicitar una nueva autorización, dejar de informar o permitir a los usuarios reparar, respectivamente.
Se deben distinguir las tareas lógicas y los registros de intentos, y solo se debe utilizar un resultado aceptado para evitar calcular mal el número de intentos como el número de solicitudes.

Volver a intentarlo después de informar un error es una práctica común, pero si lo vuelves a intentar indefinidamente y de forma indiscriminada, los fallos pueden magnificarse. Los errores de permisos, los atrasos en las cuentas, los archivos dañados y los servicios temporalmente ocupados deben manejarse de manera diferente.

Este artículo es adecuado para desarrolladores y estudiantes de productos que realizan tareas asincrónicas como traducción y conversión de documentos. Después de leer esto, primero puede categorizar las fallas y luego decidir cuánto tiempo esperar, cuántos intentos como máximo y cuándo se requiere la intervención del usuario.

El código y el flujo siguientes se basan en muestras sintéticas que se han probado en un entorno aislado. No representan una garantía de todos los documentos auténticos o efectos del producto. Conserve los originales antes de procesar documentos importantes y revíselos de acuerdo con los límites y elementos de aceptación del texto.

¿Cómo volver a intentarlo después de que la tarea del documento informe un error? Conclusión de una frase

Primero clasifique la falla antes de decidir si intentarlo nuevamente: las fallas temporales se limitan y se retiran, los problemas de permisos y cuentas se detienen y se entregan al usuario, y los errores de entrada se dejan al usuario para que los solucione.

tu situación	Prácticas recomendadas	razón
Congestión temporal del servicio	Retroceso acotado, número limitado de veces y tiempo total de espera	Evite la reedición intensiva de todas las tareas al mismo tiempo.
Inicio de sesión o permiso no válido	Solicitar al usuario que vuelva a autorizar	Reutilizar credenciales antiguas una y otra vez sólo seguirá fallando
Anormalidad en la cuenta o factura	detenerse y reportar	No debería haber recargas automáticas ni cambios de cuenta.
Error de estructura de entrada	Deja que el usuario arregle la entrada.	No tiene sentido reenviar exactamente el mismo archivo.
Tiempo de espera de solicitud POST	Primero confirme si la interfaz admite claves idempotentes o consultas de tareas.	Si el cliente no recibe una respuesta, no significa que el servidor no haya creado una tarea.

Primero determine si volver a intentar generará tareas duplicadas.

Los tiempos de espera de POST son particularmente problemáticos. Si el cliente no recibe una respuesta, no significa que el servidor no haya creado una tarea. Si la interfaz no tiene claves idempotentes y no tiene un mecanismo de consulta de tareas, el reenvío ciego puede crear múltiples tareas de traducción.

Por lo tanto, la estrategia de reintento debería seguir preferentemente el contrato de interfaz en lugar de simplemente mirar el código de estado HTTP.

Escribe el número de veces y el presupuesto de espera como funciones puras.

from enum import Enum

class Failure(Enum):
    TRANSIENT = "transient"
    AUTH = "auth"
    BILLING = "billing"
    INVALID_INPUT = "invalid_input"

def delay_for(kind, attempt, replay_safe):
    if type(attempt) is not int or attempt < 0:
        raise ValueError("invalid attempt")
    if not replay_safe or kind is not Failure.TRANSIENT:
        return None
    schedule = (1, 2, 4)
    return schedule[attempt] if attempt < len(schedule) else None

assert delay_for(Failure.TRANSIENT, 0, True) == 1
assert delay_for(Failure.TRANSIENT, 2, True) == 4
assert delay_for(Failure.TRANSIENT, 3, True) is None
assert delay_for(Failure.TRANSIENT, 0, False) is None
assert delay_for(Failure.BILLING, 0, True) is None
assert delay_for(Failure.INVALID_INPUT, 0, True) is None

Este código solo calcula el plan de reintento, en realidad no espera y no envía solicitudes. Los segundos fijos de uno, dos y cuatro son los valores de la demostración sintética y no son recomendaciones generales de servicio.

Los entornos de producción también deben considerar los siguientes puntos:

Retry-After devuelto por el servidor
Jitter aleatorio para evitar reanudar una gran cantidad de tareas al mismo tiempo
Plazo general
Límite en el número de concurrencias.

Si el tiempo de espera requerido por el servidor excede el presupuesto local, debería dejar de reintentar en lugar de iniciar la solicitud con anticipación.

Los tipos de error corresponden a diferentes acciones

fallar	Acciones opcionales	no debe hacerse por defecto
congestión temporal	evacuación limitada	Todas las tareas se reeditan intensamente al mismo tiempo.
Inicio de sesión o permiso no válido	Solicitar explícitamente una nueva autorización	Sigue repitiendo credenciales antiguas
Anormalidad en la cuenta o factura	detenerse y reportar	Recargar o cambiar de cuenta automáticamente
Error de estructura de entrada	Deja que el usuario arregle la entrada.	Reenviar exactamente el mismo archivo

Guardar tareas lógicas y registros de intentos

Una operación de usuario corresponde a una tarea lógica y puede haber varios intentos en esta tarea lógica. La hora de inicio, la categoría de error y el ID de la tarea remota se registran para cada intento. Al final, sólo se selecciona un resultado aceptado.

La ventaja de esto es que hay un registro completo al solucionar problemas de reintento y, al mismo tiempo, la cantidad de intentos no se calculará erróneamente en la cantidad de solicitudes de los usuarios.

📊 Comparación central

concepto	que grabar	efecto
Tareas lógicas	operación de un usuario	Corresponde a la misma solicitud que ve el usuario.
intenta grabar	Hora de inicio, categoría de error, ID de tarea remota	Se utiliza para solucionar problemas del proceso de reintento.
Resultados de aceptación	Un resultado que ha sido aceptado.	Como resultado de la entrega final.

La estabilidad de la experiencia de traducción proviene de explicaciones claras.

Al conectarse a OmniDoc, la interfaz debe indicarle claramente al usuario el estado actual: si está esperando, necesita ser reautorizado o necesita verificar la cuenta. No muestre todo como "Edificio".

Los usuarios están dispuestos a esperar una tarea con estado y salida, pero no están dispuestos a hacer clic repetidamente en un botón sin recibir respuesta.

Referencias: Python enum.

🎯 ¿Qué método es el adecuado para ti?

Si estás esperando que se restablezca el servicio

Utilice un retroceso acotado, establezca el número máximo de veces y el tiempo de espera total, y respete elRetry-After del servidor.

Si tienes permiso o problemas con la cuenta

Detenga los reintentos automáticos y solicite al usuario que vuelva a autorizar o verifique el estado de la cuenta.

Si la estructura de su archivo de entrada es incorrecta

Deje que el usuario repare el archivo antes de enviarlo. No reenvíe el mismo archivo.

Si la interfaz a la que llama es POST y puede que se agote el tiempo de espera

Primero confirme si la interfaz admite claves idempotentes o consultas de tareas y luego decida si desea reenviarlas.

❓ Preguntas frecuentes (FAQ)

1. ¿Se pueden reintentar directamente todos los errores informados?

No poder. Los errores de permisos, los atrasos en las cuentas, los archivos dañados y los servicios temporalmente ocupados deben tratarse por separado. Sólo los fallos temporales son adecuados para un retroceso limitado.

2. ¿Se puede enviar POST directamente nuevamente después de que expire el tiempo de espera?

No se recomienda reenviar directamente. Si el cliente no recibe una respuesta, no significa que el servidor no haya creado una tarea. Si no existe una clave idempotente o un mecanismo de consulta de tareas, pueden ocurrir tareas duplicadas.

3. ¿Cómo se debe determinar el número de reintentos y el tiempo de espera?

Los segundos fijos de uno, dos y cuatro son sólo demostraciones sintéticas. Los entornos de producción deben determinarse con una combinación de Retry-After, fluctuación aleatoria, plazos generales y límites de simultaneidad.

4. ¿La cantidad de intentos afectará las estadísticas de solicitudes de los usuarios?

No, simplemente registre una operación de usuario como una tarea lógica y registre cada reintento como un registro de intento debajo de la tarea.

📝 Resumen

La clave para volver a intentarlo no es intentarlo más veces, sino distinguir primero el tipo de fallo y luego decidir qué hacer. Las fallas que se pueden recuperar se reintentan de manera limitada y los problemas que requieren manejo humano se devuelven a los usuarios de manera oportuna.

Pruébelo ahora: cargue el documento para comenzar la traducción, conservando el diseño original