Reintentos en APIs de IA: cómo recuperarse de fallos sin duplicar solicitudes ni costes

Un reintento no es una repetición inocua

Reintentar una llamada consiste en volver a enviar una solicitud después de que un intento anterior no haya producido una respuesta utilizable para el cliente. La dificultad es que «no recibí respuesta» no equivale necesariamente a «el servidor no procesó la solicitud». La conexión puede interrumpirse antes del envío, durante la transmisión o después de que el servicio haya recibido y ejecutado la petición. En el último caso, repetirla podría generar una segunda operación o un segundo cargo, aunque el cliente solo haya visto un error de red.

Por eso, una política útil empieza antes de elegir una pausa entre intentos. Hay que saber qué operación se está repitiendo, qué resultado se conoce, qué resultado es incierto y cuánto esfuerzo adicional se permite. Una nueva consulta sin efectos externos y una operación que inicia una tarea, consume recursos o modifica estado no tienen el mismo riesgo. Tampoco conviene confundir recuperar disponibilidad con garantizar que la misma generación se ejecute una sola vez: esa garantía depende de las capacidades documentadas de la API y del diseño de la integración.

Esta guía presenta decisiones que deben adaptarse al proveedor concreto. La documentación de Kimi y ShareAI aportada aquí sirve como referencia sobre sus respectivas APIs, pero los fragmentos disponibles no confirman códigos de error concretos, cabeceras de espera ni mecanismos de idempotencia. No se deben trasladar esos detalles de un servicio a otro ni asumir que una API los ofrece porque sean habituales en otras.

Clasifica el fallo antes de decidir

No agrupes todas las respuestas fallidas bajo una única regla automática. Separa, como mínimo, los errores que indican un problema de configuración o validación, las respuestas asociadas a límites de uso, los vencimientos de espera y los fallos de conexión. Esa clasificación es un punto de partida para investigar, no una tabla universal de códigos: cada proveedor define sus respuestas y su significado. Consulta la documentación vigente de la API y registra qué señales justifican actuar en cada caso.

Un error de validación, por ejemplo, suele requerir corregir la solicitud, no enviarla otra vez sin cambios. Un límite de uso puede permitir continuar más tarde, pero hay que seguir la pauta que documente ese servicio. Un timeout o una desconexión dejan abierta otra pregunta: ¿el servicio llegó a recibir la solicitud? Si no se puede determinar, clasifica el resultado como incierto en lugar de dar por hecho que no hubo procesamiento. Esta distinción importa especialmente cuando la operación puede generar costes o efectos repetidos.

La decisión de reintentar también debe considerar si el fallo parece temporal, si repetir la misma petición tiene sentido y si queda presupuesto temporal y de intentos. La fuente secundaria sobre reintentar o cambiar de modelo recomienda acotar el reintento a fallos transitorios, a operaciones que puedan repetirse de forma segura y al presupuesto disponible. Es un criterio de diseño general, no una definición oficial de errores para ningún proveedor.

Define una política explícita y finita

Una política de reintentos debería especificar por escrito qué fallos pueden provocar un nuevo intento, cuántas veces se permite, cuánto puede durar el ciclo completo y qué hace el cliente al llegar al límite. Distingue el primer envío de los reintentos: si configuras un máximo de intentos totales, indica si ese número incluye la solicitud inicial. La precisión evita interpretaciones diferentes entre el código, la configuración y las métricas.

El límite de tiempo total —a veces llamado presupuesto temporal— debe abarcar la espera y las llamadas posteriores, no solo el tiempo de conexión de un intento. Si vence, deja de programar nuevas repeticiones aunque todavía no se haya alcanzado el máximo de intentos. A la inversa, alcanzar el máximo debe detener la secuencia aunque quede tiempo. Así se evitan ciclos ilimitados y una solicitud que retiene recursos mucho después de que el llamador pueda usar su resultado.

No hay un número de intentos ni una duración apropiados para todas las APIs. Justifica esos parámetros según la latencia tolerada por la aplicación, las indicaciones del proveedor, el coste potencial de la operación y el comportamiento medido bajo fallos. La guía de ayuda de Kimi menciona una estrategia de espera exponencial y el control del número de solicitudes; el fragmento disponible no prescribe valores universales ni confirma que esa pauta se aplique a todos los errores.

Cuando la documentación de una API indique una señal de espera, comprueba su significado y alcance y sigue la instrucción que el propio proveedor establezca. No inventes el nombre de una cabecera ni interpretes una señal de otro servicio como equivalente. Si no se ha verificado una señal documentada, el cliente no debe fingir que puede conocer el momento correcto de reanudación a partir de ella.

Esperas progresivas y dispersión aleatoria

Una espera progresiva aumenta el tiempo entre intentos consecutivos. Puede reducir la presión que genera repetir llamadas inmediatamente cuando un servicio está saturado o experimenta una interrupción. La documentación de solución de problemas de Kimi menciona la espera exponencial junto con el control del número de solicitudes. Esta referencia respalda que esos conceptos se tratan en la documentación de Kimi; no fija una configuración válida para otras APIs ni demuestra que una espera concreta sea apropiada para todos los casos.

La dispersión aleatoria, o jitter, añade variación a las pausas para que muchos clientes que fallaron al mismo tiempo no vuelvan a llamar sincronizados. Es una herramienta de diseño posible, no una obligación universal. Evalúa si encaja con las señales publicadas por el proveedor y con el plazo máximo de la operación. Si existe una instrucción de espera documentada, no la sustituyas por una pausa aleatoria que pueda contradecirla.

Documenta los parámetros elegidos y la razón de cada uno: cómo crecen las pausas, cuál es su límite, qué variación se aplica y cómo se detiene la secuencia al vencer el presupuesto. Mide el efecto con datos de operación: cantidad de intentos por solicitud, éxito tras reintento, duración total, errores finales y consumo asociado cuando se pueda medir. No conviertas una recomendación orientativa en una cifra universal sin pruebas con el proveedor y la carga reales.

Evita duplicados: idempotencia y resultado incierto

La idempotencia es una propiedad que permite repetir una operación de modo que las repeticiones no produzcan efectos adicionales, dentro de las condiciones definidas por el sistema. En una API, no basta con encontrar el término en una página: averigua si el proveedor ofrece una clave de idempotencia o un mecanismo equivalente, qué endpoints u operaciones cubre, cómo se envía, durante cuánto tiempo se reconoce y qué ocurre si se reutiliza con parámetros distintos. Solo la documentación vigente del proveedor puede confirmar esas garantías.

Las fuentes disponibles no verifican soporte de idempotencia para Kimi ni ShareAI. La página de ShareAI menciona expresamente que las escrituras requieren cuidado, pero el fragmento no confirma una clave o garantía concreta. Por tanto, no se debe afirmar que cualquiera de esos proveedores deduplica una solicitud por defecto. Si la API no documenta un mecanismo aplicable, trata una desconexión posterior al envío como un resultado potencialmente incierto y consulta qué mecanismo de reconciliación ofrece el proveedor, si lo hay.

Distingue entre volver a consultar una operación ya identificada y volver a iniciar otra. Si la API documenta un identificador consultable, úsalo solo según el alcance y el ciclo de vida que describa. Si no hay una manera documentada de comprobar el resultado, la integración tendrá que decidir entre detenerse, notificar incertidumbre o permitir una repetición con riesgo explícito. No prometas ejecución exactamente una vez sin una garantía comprobada que cubra el caso real.

Ejemplo trabajado: la respuesta se pierde tras el envío

Imagina que una aplicación envía una solicitud de generación. El cliente espera la respuesta, pero se corta la conexión. No sabe si el servidor recibió la petición, si empezó a procesarla o si terminó. En lugar de repetir automáticamente, marca el intento como incierto y consulta la documentación de esa API: ¿hay una clave de idempotencia aplicable?, ¿existe una forma documentada de consultar el estado?, ¿qué política establece el proveedor para este tipo de interrupción? La respuesta determina la siguiente acción.

Si hay un mecanismo documentado que cubre esta operación, la integración puede repetir o consultar siguiendo exactamente su alcance. Si no lo hay, no puede deducir del error de transporte que el servicio no procesó la solicitud. El equipo debe aplicar la política de riesgo previamente aprobada: por ejemplo, detener y mostrar un estado pendiente de revisión, o permitir una repetición dejando claro que podría producir otro consumo. La opción adecuada depende del impacto de duplicar la operación y de los mecanismos disponibles; no existe una respuesta universal.

Si el proveedor responde de forma definitiva, el ciclo termina según el significado documentado de esa respuesta. Si devuelve éxito, no se programan más intentos. Si se confirma un fallo temporal y la repetición es segura, se comprueban de nuevo el límite, el presupuesto y la espera. Si el presupuesto vence o se alcanza el máximo, la secuencia termina y el sistema registra el resultado final o incierto. En ningún punto se debe reiniciar el contador simplemente porque cambió el proceso que atiende la solicitud.

Prueba fallos realistas antes del despliegue

Las pruebas deben comprobar tanto la decisión de reintentar como la decisión de detenerse. Simula un fallo que la configuración clasifique como temporal y verifica que el cliente respeta el límite. Simula fallos persistentes y confirma que no se repite indefinidamente. Haz vencer el presupuesto temporal mientras todavía quedarían intentos disponibles; después, comprueba que alcanzar el máximo también corta el ciclo aunque quede tiempo.

Incluye una respuesta tardía y una desconexión justo después del envío. Son casos distintos: la respuesta tardía puede llegar cuando el cliente ya considera vencida su espera, mientras que la desconexión posterior al envío deja incierto el estado del procesamiento. Verifica que la aplicación no duplica una operación por suponer que ambas situaciones significan «el servidor no hizo nada». Si el proveedor ofrece una función de idempotencia, las pruebas deben confirmar su alcance en un entorno adecuado y con la documentación vigente, no simular una garantía que el servicio no ha prometido.

Añade casos de error de validación y de límites de uso para comprobar que no se aplica una regla genérica a todas las respuestas. Si hay señales de espera publicadas por el proveedor, prueba su interpretación documentada. Por último, verifica que los registros permiten reconstruir el orden de los intentos sin guardar innecesariamente prompts, respuestas ni datos sensibles. Los identificadores de correlación, el tipo de resultado, los tiempos y el número de intento suelen ser más útiles para el diagnóstico que copiar todo el contenido de la solicitud.

Criterios para poner la política en producción

Antes del despliegue, deja registrado qué documentación consultaste, cuándo la verificaste y para qué versión o endpoint aplica. Mantén separadas las instrucciones del proveedor y las decisiones propias de la aplicación: una recomendación documentada no sustituye el análisis del riesgo de duplicado, y una política local no debe presentarse como garantía del servicio.

Revisa los resultados después del despliegue. Un aumento de intentos por llamada, de ciclos agotados o de resultados inciertos puede señalar una degradación, una configuración demasiado agresiva o un cambio en la conducta del servicio. Trata el fallback —por ejemplo, una ruta alternativa aprobada— como una decisión distinta del reintento: la fuente secundaria sobre APIs de LLM recomienda cambiar de ruta solo hacia una alternativa previamente aprobada. Verifica compatibilidad, calidad, privacidad y costes antes de activar un fallback; no lo uses para ocultar que la llamada original pudo haberse procesado.

Por último, mide por separado la recuperación técnica y la calidad de la respuesta. Que una llamada termine con éxito después de varios intentos no demuestra que el contenido generado sea correcto o adecuado. Una política robusta limita daños y clarifica resultados; no reemplaza la evaluación de la salida del modelo ni las decisiones de seguridad de la aplicación.

Continúa explorando

Correcciones y transparencia

Si detectas un dato incorrecto o desactualizado, puedes enviarnos una corrección indicando la página y la fuente que debemos revisar.