Idempotencia y reintentos vía proxy: cómo repetir una solicitud no genera pedidos duplicados
Contenido del artículo
- Introducción: un botón, dos pedidos y un túnel donde se pierden las respuestas
- Fundamentos: qué es la idempotencia y por qué repetir una solicitud es peligroso
- Inmersión profunda: el contrato del servidor y la anatomía de un reintento seguro
- Método 1: generación y envío de la clave de idempotencia del lado del cliente
- Método 2: implementación del almacén de claves del lado del servidor
- Método 3: protocolo de reintentos a través de proxy que no rompe la idempotencia
- Método 4: cuando el servidor no soporta claves de idempotencia
- Errores típicos: cómo los equipos generan duplicados solos
- Herramientas y recursos para la implementación
- Casos y resultados
- Faq: preguntas difíciles sobre idempotencia y reintentos
- Conclusión: contrato en lugar de esperanza
Introducción: un botón, dos pedidos y un túnel donde se pierden las respuestas
Imagina una integración que lleva años funcionando. Tu servicio envía pedidos a un sistema externo, el flujo pasa por un pool de proxies móviles para distribuir las solicitudes por regiones y no chocar con los límites de una sola dirección. Todo estable. Y de pronto contabilidad trae un reporte: en un mes aparecieron cuarenta y siete pedidos gemelos en el sistema del socio. Mismos productos, mismos montos, diferencia de tres o cuatro segundos entre creaciones. Nadie cambió nada. ¿Qué pasó?
Pasó lo más común: la conexión a través del proxy se cortó en el camino de vuelta. El servidor recibió la solicitud, creó el pedido, envió la respuesta, pero la respuesta nunca llegó al cliente. El cliente asumió honestamente que la solicitud había fallado y la repitió. La segunda solicitud también se ejecutó. Así nace un duplicado, y ninguna política de reintentos por sí sola lo evita.
Conviene trazar una frontera de inmediato. Sobre cómo repetir solicitudes tras un error 429, cuánto esperar entre intentos y cómo construir una espera exponencial escribimos en otro artículo: ese es el tema de la política de reintentos. Hoy la conversación es otra. Hablamos del contrato entre cliente y servidor que hace que el reintento sea seguro o peligroso, sin importar cómo lo ejecutes. Ese contrato se llama idempotencia, y su herramienta principal es la clave de idempotencia.
¿Por qué el tema es especialmente crítico justo cuando se trabaja a través de proxies? Porque el proxy agrega un tramo más a la cadena donde la respuesta puede perderse. Además, los proxies móviles cambian la IP externa al rotar, y el servidor perfectamente puede ver la segunda solicitud desde otra dirección. Si tu protección contra duplicados se apoya en la sesión, la IP o una ventana de tiempo, se desmorona. Si se apoya en la clave de idempotencia, le da igual de dónde venga el reintento.
En esta guía vas a aprender cómo funciona la idempotencia a nivel de protocolo y de lógica de negocio, cómo generar y almacenar claves, cómo diseñar un almacén del lado del servidor que aguante reintentos concurrentes, qué hacer si la API externa no soporta claves, y en qué errores tropiezan incluso los equipos experimentados. Vamos a revisar casos con cifras, armar checklists y responder preguntas incómodas. El material está pensado para desarrolladores de integraciones, arquitectos y líderes técnicos que trabajan con pedidos, pagos y cualquier operación donde "dos veces" significa "mal"
Fundamentos: qué es la idempotencia y por qué repetir una solicitud es peligroso
Definición en palabras simples
Una operación es idempotente si ejecutarla varias veces produce el mismo resultado que ejecutarla una sola vez. Apretar el botón del ascensor diez veces es idempotente: el ascensor viene una vez. Agregar otra unidad de un producto al carrito no es idempotente: cada pulsación cambia el estado. Transferir dinero definitivamente no es idempotente, a menos que el sistema esté diseñado a propósito para que repetir la transferencia con el mismo identificador no haga nada.
En HTTP hay métodos que por especificación se consideran idempotentes: GET, PUT, DELETE, HEAD. Y está el método POST, que por defecto no se considera idempotente. Justamente POST es el que más se usa para crear pedidos, pagos, enviar mensajes. Es decir, la operación más riesgosa vive en el método menos idempotente. ¿Casualidad? Más bien una regularidad histórica con la que hay que convivir.
Tres desenlaces posibles de cualquier solicitud
Cuando el cliente envía una solicitud y no recibe respuesta, queda en un estado de incertidumbre. Hay exactamente tres escenarios:
- La solicitud no llegó al servidor. Repetir es seguro: no pasó nada.
- La solicitud llegó, el servidor ejecutó la operación, la respuesta se perdió. Repetir es peligroso: la operación se ejecutará por segunda vez.
- La solicitud llegó, el servidor empezó a ejecutarla y todavía no terminó. Repetir es doblemente peligroso: dos operaciones se ejecutarán en paralelo.
El problema clave es que el cliente no puede distinguir estos escenarios. Un timeout se ve igual en los tres casos. Una conexión cortada, también. De ahí se desprende un principio fundamental de los sistemas distribuidos: la entrega confiable solo es posible como "al menos una vez" (at-least-once). La garantía "exactamente una vez" (exactly-once) no se puede obtener a nivel de transporte; solo se puede emular a nivel de aplicación haciendo que los reintentos sean inofensivos. La idempotencia es ese mecanismo de emulación.
Cómo el proxy alarga la cadena de incertidumbre
Sin proxy, entre cliente y servidor hay un solo tramo de red. Con proxy hay dos: cliente-proxy y proxy-servidor. La respuesta puede perderse en cualquiera de los dos. Y si se pierde en el primer tramo, el proxy ya recibió la respuesta, el servidor ya completó la operación, y el cliente nunca lo sabrá.
Los proxies móviles agregan matices. Tienen rotación de IP por horario o a demanda, cambio entre estaciones base, fluctuaciones naturales en la calidad del canal de radio. Cada uno de esos eventos puede romper una conexión TCP en cualquier momento. Y lo más frecuente es que la ruptura no ocurra durante el envío del cuerpo de la solicitud (es pequeño y sale rápido), sino durante la espera de la respuesta, cuando la conexión simplemente se mantiene abierta. Justo en ese momento el servidor está procesando tu pedido. Justo en ese momento la ruptura maximiza la probabilidad de un duplicado.
Qué es una clave de idempotencia
Una clave de idempotencia (Idempotency-Key) es un identificador único de una operación de negocio que el cliente genera una sola vez y envía con cada intento de ejecutar esa operación. El servidor memoriza la clave y el resultado. Ante una nueva solicitud con la misma clave, el servidor no ejecuta la operación otra vez, sino que devuelve el resultado guardado. El cliente puede repetir cuantas veces quiera: el pedido se creará una sola vez.
Fíjate en la formulación: la clave identifica una operación, no una solicitud HTTP. Esa distinción será central más adelante, cuando analicemos errores de implementación.
Inmersión profunda: el contrato del servidor y la anatomía de un reintento seguro
El contrato como acuerdo de comportamiento
La idempotencia no es un encabezado ni una librería. Es un contrato, donde el servidor le promete al cliente un comportamiento concreto ante reintentos, y el cliente promete respetar las reglas de formación de claves. Un buen contrato responde a las siguientes preguntas:
- ¿Qué entidad es la unidad de idempotencia: el pedido, el pago, la línea del pedido, el lote?
- ¿Cómo envía el cliente la clave: encabezado, campo del cuerpo, parte de la URL?
- ¿Qué pasa si la clave coincide pero el cuerpo de la solicitud es distinto?
- ¿Qué pasa si la primera solicitud todavía se está ejecutando y llega una segunda con la misma clave?
- ¿Cuánto tiempo recuerda el servidor la clave?
- ¿Qué se devuelve ante un reintento: exactamente la misma respuesta byte a byte o el estado actual de la entidad?
- ¿Cómo se distingue un reintento de una solicitud nueva en los logs y en las métricas?
Si al menos una de estas preguntas no tiene respuesta en la documentación de la API, el contrato está incompleto, y en situaciones indefinidas el comportamiento dependerá de la implementación, de la versión y de la fase de la luna.
Tres estados de una clave
En el servidor, cada clave tiene un ciclo de vida de tres estados. Entender ese ciclo explica el noventa por ciento de los problemas con duplicados.
- Ausente. La clave se ve por primera vez. El servidor debe reservarla de forma atómica y comenzar el procesamiento.
- En proceso (in-progress). La primera solicitud se está procesando. Una segunda solicitud con la misma clave no debe disparar un segundo procesamiento. Opciones: devolver 409 Conflict indicando que espere, bloquear hasta que termine la primera y devolver su resultado, o devolver 202 Accepted con un enlace al estado.
- Completado. El resultado está guardado. Un reintento devuelve el resultado almacenado sin efectos secundarios.
El error arquitectónico más común es omitir el estado intermedio. El desarrollador comprueba "¿existe la clave en la base?", no la encuentra, empieza a procesar, y un reintento paralelo en ese mismo instante hace lo mismo. Dos hilos, dos comprobaciones, dos pedidos. La comprobación y la reserva deben ser una sola operación atómica: inserción con índice único, escritura condicional en Redis, transacción con bloqueo.
El fingerprint de la solicitud
La clave identifica la operación, pero ¿una operación con qué contenido? Si el cliente, por un bug, envió la clave K con un monto de 1000 pesos, y luego repitió con la misma clave y un monto de 10000, ¿qué debería hacer el servidor? Devolver en silencio el resultado de la primera operación es peligroso: el cliente va a creer que pagó 10000. Ejecutar la segunda rompe la idempotencia.
La respuesta correcta: el servidor guarda un fingerprint de la solicitud, un hash del cuerpo normalizado y de los encabezados relevantes. Si llega un reintento con la misma clave pero distinto fingerprint, devuelve un error 422 Unprocessable Content o 400 con un código explícito del estilo idempotency_key_reused_with_different_payload. Esto protege contra errores lógicos del cliente y contra reintentos falsificados.
Almacenamiento de la respuesta: instantánea o estado actual
Existen dos enfoques sobre qué devolver ante un reintento. La instantánea: el servidor guarda el estado, los encabezados y el cuerpo de la respuesta original, y los devuelve sin cambios. Es estrictamente idempotente y predecible. El estado actual: el servidor busca por la clave la entidad creada y devuelve su representación vigente. Es más cómodo si entre intentos el pedido pasó a otro estado, pero es menos predecible.
En los sistemas de pago domina la instantánea: el cliente debe recibir exactamente la respuesta del primer intento. En los sistemas de gestión de pedidos suele aplicarse un híbrido: instantánea para los códigos de error, estado actual para el éxito. Lo importante es que la elección quede fijada en el contrato.
Qué cambia el proxy a nivel del contrato
Técnicamente el proxy no participa en el contrato de idempotencia: es transparente a los encabezados y al cuerpo. Pero cambia las probabilidades. Con conexión directa, perder la respuesta de una ejecución exitosa es rarísimo, una fracción de un uno por ciento. Con una cadena con proxy móvil y rotación, ese evento se vuelve habitual. Hemos observado integraciones donde, con rotación de IP cada cinco minutos, entre el 0,3% y el 0,8% de las solicitudes terminaban en corte de conexión durante la espera de la respuesta. Con diez mil pedidos diarios, eso son entre treinta y ochenta duplicados potenciales todos los días. Sin clave de idempotencia, cada uno se convierte en un duplicado real.
Hay un segundo matiz. Muchos servidores incluyen en su lógica antifraude la comprobación de "solicitud repetida desde otra IP". Con rotación de proxy móvil, el reintento casi siempre llegará desde una dirección nueva. Si el servidor lo interpreta como actividad sospechosa y rechaza el reintento sin consultar el almacén de claves, el cliente no recibirá el resultado guardado y quedará en la incertidumbre. Un buen contrato verifica la clave antes de cualquier heurística atada a la red.
Método 1: generación y envío de la clave de idempotencia del lado del cliente
Dónde nace la clave
La regla principal: la clave se genera una sola vez por operación de negocio, antes del primer intento de envío, y se guarda junto con la intención de ejecutar la operación. Si la clave se crea dentro del cliente HTTP en cada llamada, el reintento obtendrá una clave nueva y toda la protección se anulará. Este error es tan frecuente que lo listamos aparte en la sección de antipatrones, pero lo repetimos aquí: la clave vive a nivel del servicio de pedidos, no a nivel del transporte.
La secuencia práctica es así:
- El usuario o un proceso interno inicia la creación del pedido.
- El servicio crea un registro local de "intención de pedido" en estado pending y genera la clave.
- La clave y la carga útil se guardan en la base local en una sola transacción.
- Solo después de confirmar la transacción se dispara el envío a la API externa a través del proxy.
- Todos los reintentos leen la clave del registro local, no generan una nueva.
- Al recibir la respuesta, el registro local se actualiza con el resultado y el identificador externo del pedido.
Este orden garantiza que incluso un reinicio de tu servicio en medio de los reintentos no provoque un cambio de clave: está en la base.
Formato de la clave
La clave debe ser globalmente única e impredecible para terceros. Opciones viables:
- UUID versión 4: el clásico, 122 bits de aleatoriedad, sirve en cualquier contexto.
- UUID versión 7 o ULID: contienen una marca temporal en los bits altos, lo que las hace cómodas para ordenar e indexar en la base del servidor. En 2026 ya es la elección estándar para sistemas nuevos.
- Clave determinista a partir de un identificador natural: por ejemplo, el hash del identificador del carrito, del identificador del usuario y de la versión del carrito. Es útil cuando el cliente mismo puede perder el estado y regenerar la clave a partir de los mismos datos.
Qué evitar: números secuenciales (es fácil adivinar la clave ajena y obtener su respuesta), cadenas cortas, claves que dependen solo del tiempo con baja precisión.
Forma de envío
El estándar de facto es el encabezado Idempotency-Key. El borrador de especificación del IETF fija justamente ese nombre, y la mayoría de las API modernas lo respetan. Ejemplo de llamada a través de proxy:
curl -x http://user:pass@proxy.example:8080 -H "Idempotency-Key: 018f3a2c-7b1e-7c3d-9a4e-1f2b3c4d5e6f" -H "Content-Type: application/json" -d '{"cart_id":"c-9921","amount":149000}' https://api.partner.example/v1/orders
Algunas API aceptan la clave en el cuerpo de la solicitud (campo client_reference_id, external_id, request_id). También es una opción válida, pero con un matiz: si el servidor usa un campo del cuerpo como clave, ese campo debe formar parte del índice único; de lo contrario es solo una etiqueta, no una protección.
Ámbito de la clave
La clave debe ser única dentro de una misma cuenta de cliente y un mismo endpoint. Un buen servidor compone la clave interna de almacenamiento como la combinación del identificador de cuenta, el método, la ruta y la clave enviada. Esto protege contra colisiones entre clientes distintos y contra la reutilización accidental de una clave para otra operación.
Checklist del lado del cliente
- La clave se genera antes del primer intento y se guarda en la base junto con la intención.
- Todos los reintentos usan la misma clave.
- El cuerpo de la solicitud en el reintento coincide byte a byte con el primer intento.
- El cliente sabe tratar un 409 (operación en proceso) como señal de esperar y reintentar, no como error.
- El cliente sabe tratar un 422 con código de desajuste de fingerprint como error lógico que requiere intervención.
- El cliente registra la clave en todos los logs asociados a la operación, para poder investigar los duplicados.
- El cliente no descarta la clave al cambiar de proxy, rotar de IP o pasar a un pool de respaldo.
Método 2: implementación del almacén de claves del lado del servidor
Si eres dueño del servidor al que tus clientes o socios llegan a través de un proxy, esta sección es para ti. Si eres solo cliente, te ayudará a evaluar la calidad de una implementación ajena por su documentación y su comportamiento.
Esquema de almacenamiento
La tabla o estructura mínima para las claves contiene los siguientes campos:
- scope_key: clave compuesta: cuenta, método, ruta, Idempotency-Key enviada. Índice único.
- fingerprint: hash del cuerpo normalizado de la solicitud.
- state: uno de los valores: in_progress, completed, failed.
- response_status, response_headers, response_body: instantánea de la respuesta, se llena al completar.
- resource_id: identificador de la entidad creada, si aplica.
- locked_at, completed_at, expires_at: marcas temporales para tratar operaciones colgadas y limpiar.
Reserva atómica
El corazón de la implementación es la operación que, en un solo paso, o crea un registro en estado in_progress o informa que el registro ya existe. En una base relacional esto es una inserción con manejo de conflicto por índice único. En Redis es el comando SET con los flags NX y EX, que escribe el valor solo si la clave no existe y de inmediato fija el tiempo de vida. Nada de "primero SELECT, después INSERT": entre ambos se cuela un reintento paralelo.
Pseudocódigo a nivel de lógica:
- Calcular scope_key y fingerprint.
- Intentar insertar el registro con state = in_progress. Si la inserción es exitosa, pasar a ejecutar la operación.
- Si hay conflicto: leer el registro existente.
- Si el fingerprint no coincide, devolver 422 con código de desajuste.
- Si state = in_progress, devolver 409 con encabezado Retry-After o esperar a que termine (dentro de un timeout razonable).
- Si state = completed, devolver la instantánea guardada de la respuesta con un encabezado que marque el reintento, por ejemplo
Idempotent-Replayed: true.
Ejecución y fijación del resultado
Aquí está la segunda trampa. La operación se ejecutó, el pedido se creó, pero el proceso cayó antes de escribir el resultado en el almacén de claves. El registro queda en estado in_progress para siempre. El reintento recibe 409, después otro 409, y así hasta el infinito.
Hay tres enfoques para resolverlo:
- Transacción única. La creación del pedido y la actualización del registro de la clave se ejecutan en una sola transacción de base de datos. La opción más confiable si el pedido y las claves viven en la misma base.
- Clave como parte de la entidad. La clave de idempotencia se guarda directamente en la tabla de pedidos con índice único. Entonces el propio pedido es el registro de la clave; no hace falta una tabla aparte. Simple y confiable para casos con una sola entidad por operación.
- Recuperación de colgados. Un proceso en segundo plano encuentra registros in_progress más antiguos que un umbral (por ejemplo, 60 segundos), verifica si la operación se ejecutó de hecho (por resource_id o buscando la entidad) y, o completa la fijación, o pasa el registro a failed, permitiendo el reintento.
Manejo de errores del primer intento
¿Qué guardar si el primer intento terminó en error? Depende del tipo de error. Los errores de validación (400, 422) son deterministas: repetir con el mismo cuerpo dará el mismo resultado, se pueden cachear. Los errores de infraestructura (500, 503, timeout de base) no son deterministas: si los cacheas, el cliente nunca podrá ejecutar la operación con éxito. El comportamiento correcto: ante un error de infraestructura, liberar la clave (borrar el registro o pasarlo a failed con posibilidad de recaptura), para que el siguiente reintento lo intente de nuevo.
Tiempo de vida de la clave
Las claves no se pueden guardar para siempre: la tabla crecerá sin control. Pero un plazo demasiado corto también es peligroso: si el cliente reintenta media hora después de una avería de red, la clave debe seguir viva. La práctica de los grandes proveedores de pago converge en 24 horas como mínimo. Para pedidos de comercio electrónico son razonables 24-72 horas. Para operaciones que el cliente puede reintentar tras fallos prolongados (por ejemplo, sincronización de catálogos una vez al día), el plazo debe superar al menos al doble el intervalo de sincronización.
Observabilidad
Cada reintento debe dejar huella. Métricas que conviene recolectar: cantidad de reintentos que caen en completed (reintentos inofensivos), cantidad de 409 (reintentos concurrentes), cantidad de 422 (desajuste de fingerprint: casi siempre un bug del cliente), edad del registro in_progress más antiguo (indicador de operaciones colgadas). La relación entre reintentos y operaciones únicas es una medida directa de la calidad de red entre cliente y servidor. Si sube de golpe, en algún punto empeoró la calidad del canal de proxy o cambió la rotación.
Checklist del lado del servidor
- La reserva de la clave es atómica.
- Existe un estado in_progress aparte y una respuesta clara al reintento concurrente.
- Se guarda el fingerprint del cuerpo y el desajuste se rechaza con un error explícito.
- La fijación del resultado es transaccional o hay un mecanismo de recuperación de registros colgados.
- Los errores de infraestructura no se cachean; los deterministas sí.
- El TTL no es menor a 24 horas y está documentado.
- El reintento se marca con un encabezado y se ve en las métricas.
- La verificación de la clave ocurre antes de las heurísticas de red del antifraude.
Método 3: protocolo de reintentos a través de proxy que no rompe la idempotencia
La política de reintentos es tema de otro artículo, pero hay una capa estrecha donde política de reintentos e idempotencia se cruzan: qué señales exactas de la cadena de proxy indican que hace falta reintentar, y cómo el reintento no debe destruir el contrato. Vamos a desglosarla.
Distingue el fallo del proxy del fallo del upstream
Al trabajar a través de proxy, el cliente recibe errores de tres orígenes, y hay que reaccionar distinto a cada uno:
- Errores de conexión con el proxy. No se pudo conectar al proxy, el proxy devolvió 407 (se requiere autenticación), el proxy cerró la conexión antes de enviar la solicitud. La solicitud garantizadamente no llegó al servidor. Reintentar es seguro incluso sin clave, pero con clave es mejor igual.
- Errores del proxy al contactar al upstream. El proxy devolvió 502 Bad Gateway o 504 Gateway Timeout. Aquí la incertidumbre es máxima: 502 normalmente significa que el upstream no respondió correctamente, pero pudo haber ejecutado la operación; 504 significa que el proxy se cansó de esperar y el servidor quizá todavía está procesando. Reintento solo con clave.
- Respuestas del upstream que pasaron por el proxy. 500, 503, 429 del servidor de destino. Su semántica la define el contrato de la API destino. Reintento con clave según las reglas de la política de reintentos.
Merece atención aparte el corte de conexión durante la lectura de la respuesta. Los encabezados ya llegaron, el cuerpo se cortó. Es el caso más traicionero: quizá viste el estado 201 Created, pero no obtuviste el identificador del pedido del cuerpo. Un reintento con clave devolverá la instantánea completa de la respuesta. Sin clave, obtendrás un segundo pedido y encima nunca sabrás el identificador del primero.
La rotación de IP como evento, no como fondo
Si tu pool de proxies móviles rota direcciones por horario, sincroniza el envío de operaciones críticas con las ventanas de estabilidad. Un truco simple: preguntarle a la API del servicio de proxy cuánto falta para la próxima rotación, y no empezar la creación del pedido si falta menos que tu timeout de espera de respuesta. Esto no reemplaza la idempotencia, pero reduce el número de reintentos y, con eso, la carga sobre el almacén de claves y sobre el antifraude del socio.
Si la rotación ocurre a demanda, no provoques un cambio de IP entre intentos de una misma operación sin necesidad. Algunos equipos lo hacen "para sortear el pegado", pero el servidor, al ver la misma clave desde una dirección nueva, puede activar una verificación adicional. La clave te salvará del duplicado, pero el reintento puede volverse más lento.
Timeouts: dos fronteras en lugar de una
Con conexión directa se suele fijar un solo timeout de respuesta. A través de proxy hacen falta al menos dos: timeout de establecimiento de conexión con el proxy (corto, de unos segundos) y timeout de espera de respuesta del upstream (más largo, considerando el tiempo de procesamiento del pedido). Si los juntas en uno solo, un timeout corto se disparará constantemente con procesamiento lento, generando reintentos de más; y uno largo te hará esperar segundos de más ante un proxy caído.
Importante: el timeout de espera de respuesta no debe ser menor al tiempo real de creación del pedido en el servidor. De lo contrario, cortarás la conexión sistemáticamente justo en el momento del procesamiento, y cada operación se convertirá en la pareja "intento cortado más reintento". La clave evitará duplicados, pero el servidor gastará recursos procesando en el vacío.
Reintento a través de otro proxy
Una estrategia sensata: el primer reintento va por el mismo proxy (quizá la conexión solo parpadeó), el segundo por otro proxy del pool (quizá el problema está en un canal concreto). La clave no cambia. El cuerpo no cambia. Solo cambia la ruta. Así separas problemas de red de problemas de la solicitud y obtienes información de diagnóstico: si por el segundo proxy pasó de inmediato, el problema estaba en el canal.
Protocolo paso a paso de un reintento seguro
- Leer la clave y el cuerpo del registro local de intención.
- Enviar la solicitud a través del proxy actual con los dos timeouts.
- Si hay éxito: guardar el resultado, terminar.
- Si el servidor devuelve 409: esperar el tiempo indicado o un intervalo razonable, reintentar con la misma clave.
- Si devuelve 422 con código de desajuste de fingerprint: detenerse, levantar un incidente, no reintentar automáticamente.
- Si hay error de conexión con el proxy: cambiar de proxy, reintentar de inmediato.
- Si hay 502, 504, corte o timeout: aplicar la política de espera, reintentar con la misma clave; a partir del segundo reintento, por otro proxy.
- Tras agotar los intentos: dejar el registro en estado unknown, pasarlo a la cola de conciliación (ver Método 4).
El punto ocho es crítico. El estado "no sé si el pedido se creó" es un estado legítimo, y no se puede colapsar en silencio ni en "creado" ni en "no creado".
Método 4: cuando el servidor no soporta claves de idempotencia
El mundo ideal se acaba en la primera API de socio cuya documentación no menciona la palabra "idempotencia". ¿Qué hacer si eres cliente y el servidor simplemente crea un pedido por cada POST? Hay varias técnicas, de las simples a las arquitectónicas.
Clave natural en campos de la solicitud
Muchas API, sin tener un Idempotency-Key formal, aceptan un campo del estilo external_order_id, client_reference, merchant_order_number y prometen unicidad por él dentro de la cuenta. Eso es idempotencia con otro nombre. Revisa la documentación y, sobre todo, verifica el comportamiento: envía dos solicitudes con el mismo identificador externo en el entorno de pruebas y mira si devuelve un error de duplicado o crea una segunda entidad. Las promesas de la documentación y el comportamiento real difieren más de lo que uno querría.
Lectura antes del reintento
Si el servidor permite buscar entidades por tu identificador externo o por parámetros (por ejemplo, una lista de pedidos filtrada por hora y monto), antes de cada reintento haz una solicitud de verificación: ¿ya apareció un pedido con mis rasgos? No da una garantía estricta (entre la verificación y el reintento puede colarse una ventana), pero reduce la probabilidad de duplicado en un orden de magnitud. El esquema:
- El primer intento terminó de forma indefinida.
- Esperar un intervalo suficiente para que el procesamiento en el servidor termine.
- Ejecutar un GET con filtro por identificador externo o por la combinación única de campos.
- Si el pedido aparece, fijar su identificador; el reintento no hace falta.
- Si no aparece, reintentar el POST.
Para que la búsqueda funcione, incluye en el pedido una marca que permita encontrarlo: comentario, campo personalizado, número único de posición. Aunque el servidor la ignore como clave, la devolverá en la respuesta y podrás cotejar.
Dividir la operación en reserva y confirmación
Algunas API soportan un modelo de dos fases: primero se crea un borrador o una retención (una operación que se puede repetir o cancelar sin riesgo), luego la confirmación por el identificador del borrador. La confirmación por identificador es idempotente por naturaleza: no se puede confirmar dos veces el mismo borrador. Si ese modelo está disponible, es preferible a la creación en un solo paso incluso habiendo claves, porque reduce la ventana de incertidumbre del paso más riesgoso.
Patrón Outbox de tu lado
Incluso si el servidor no garantiza nada, tú puedes garantizar que de tu lado cada operación salga con una sola intención. El Outbox transaccional es una tabla de operaciones salientes donde el registro entra en la misma transacción que el cambio de negocio (por ejemplo, con el paso del carrito al estado "en proceso de pedido"). Un proceso emisor aparte toma los registros del Outbox y ejecuta las solicitudes a través del proxy. Cada registro tiene un identificador único que usas como clave o como external_id. Incluso si el emisor cae en medio del trabajo, el registro queda en el Outbox y el reintento saldrá con el mismo identificador.
La conciliación como última línea de defensa
La conciliación (reconciliation) es un proceso regular que compara tu lista de operaciones con la lista de entidades del lado del socio y encuentra discrepancias: pedidos que existen en el socio pero no están vinculados de tu lado; operaciones en estado unknown; duplicados por rasgos coincidentes. La conciliación no evita el duplicado, pero lo encuentra en minutos, no en un mes por el reporte de contabilidad. Para operaciones por canales inestables es un componente obligatorio, no una opción.
En la práctica: correr la conciliación cada 10-15 minutos para operaciones más antiguas que tu timeout máximo de reintentos, vincular automáticamente las entidades encontradas con los registros en unknown, y pasar los duplicados detectados a una cola de cancelación con confirmación manual si el monto supera el umbral.
Saga y compensaciones
Si el pedido es parte de una cadena de acciones (reserva de stock, pago, entrega), un duplicado en un eslabón rompe toda la cadena. El patrón saga supone que cada paso tiene una acción compensatoria: cancelar el pedido, devolver el pago, liberar la reserva. La compensación también debe ser idempotente; de lo contrario, estarás peleando con duplicados de cancelaciones. Al diseñar la integración, escribe de una vez los pares "acción - compensación" y verifica en ambos que el reintento sea seguro.
Errores típicos: cómo los equipos generan duplicados solos
Error 1. La clave se genera dentro del cliente HTTP
El más frecuente. El wrapper sobre la librería HTTP agrega el encabezado Idempotency-Key con un UUID nuevo en cada llamada. El mecanismo de reintentos dentro de esa misma librería dispara el envío de nuevo, y obtiene una clave nueva. Visto desde fuera todo parece correcto: el encabezado está. En la práctica no hay protección. Verifica en los logs del servidor o del proxy que en los reintentos la clave coincida.
Error 2. La clave cambia junto con el cuerpo al "corregir" la solicitud
El cliente recibió un 400 por un campo inválido, corrigió el campo y reintentó con la misma clave. El servidor con verificación de fingerprint devolverá 422. El servidor sin verificación devolverá el error 400 cacheado, y el cliente se estrellará contra un muro. Una solicitud corregida es una operación nueva; necesita una clave nueva.
Error 3. Verificar la clave con SELECT y luego INSERT
Ya lo analizamos, pero lo repetimos: entre la lectura y la escritura se alcanza a colar un reintento paralelo. Es especialmente frecuente justo al trabajar a través de proxy, porque los timeouts del cliente generan reintentos con intervalos de pocos segundos, y el procesamiento del pedido dura lo mismo. Solo reserva atómica.
Error 4. Idempotencia por IP o por sesión
El servidor "recuerda" que desde esa IP acaba de haber una solicitud igual y rechaza el reintento. Con la rotación del proxy móvil, el reintento llega desde otra dirección y la protección no se activa. El caso inverso también es malo: pedidos legítimos distintos desde una misma dirección de proxy (tienes muchos clientes detrás de una IP) se rechazan como duplicados. La clave debe ser explícita y enviada por el cliente.
Error 5. TTL demasiado corto
Las claves viven cinco minutos, "para no ensuciar Redis". La avería de red dura veinte minutos. La cola de reintentos llega a la operación media hora después. La clave ya se olvidó, el pedido se crea por segunda vez. El TTL debe cubrir el escenario realista más largo de reintento diferido.
Error 6. Cachear errores de infraestructura
El primer intento cayó con 500 por indisponibilidad temporal de la base. El servidor guardó el 500 como resultado por clave. Todos los reintentos posteriores reciben 500 de la caché, aunque la base ya se levantó hace rato. El cliente se ve obligado a cambiar la clave, perdiendo el vínculo con la operación original. Solo se pueden cachear resultados deterministas.
Error 7. Colapsar el estado unknown
Tras agotar los intentos, el cliente marca la operación como failed y le permite al usuario hacer el pedido de nuevo. Pero el servidor ya ejecutó la primera operación. El usuario termina con dos pedidos y dos cargos. El estado unknown debe existir explícitamente y resolverse por conciliación, no por una suposición optimista.
Error 8. Reintentar operaciones no idempotentes "porque es más simple"
Una capa universal de reintentos repite todas las solicitudes por igual, incluidos los POST sin claves. Eso funciona hasta la primera tormenta de red, tras la cual aparecen cientos de duplicados en una hora. La capa de reintentos debe saber qué solicitudes se pueden repetir y negarse a repetir las no idempotentes sin una clave explícita.
Error 9. Una sola clave para todo un lote
El cliente envía un arreglo de cien pedidos con una sola clave. El servidor procesó sesenta y cayó. El reintento con la misma clave recibe un 409 o una instantánea parcial. ¿Cómo saber cuáles cuarenta hay que crear? Para los lotes hace falta una clave por posición, o una garantía del servidor de atomicidad del lote completo, o una respuesta con estado por elemento. Sin eso, los lotes por un canal inestable son una fuente de caos.
Error 10. Ausencia de la clave en los logs
Ocurrió el duplicado y tratas de entender si fue un reintento con la misma clave (bug del servidor) o dos operaciones distintas (bug del cliente). En los logs no hay clave. La investigación se vuelve adivinación. La clave debe estar en cada línea de log de ambos lados y en el registro del proxy, si el servicio de proxy soporta el registro de encabezados.
Herramientas y recursos para la implementación
Del lado del cliente
- Librerías de identificadores. Hay generadores de UUIDv7 y ULID para todos los lenguajes principales. Elige los que garanticen monotonicidad dentro del milisegundo, si las claves van a índices de la base del servidor.
- Clientes HTTP con timeouts separados. Asegúrate de que tu cliente permita fijar por separado el timeout de conexión al proxy y el de lectura de la respuesta. La mayoría de los clientes modernos lo permiten, pero por defecto suele haber un timeout único.
- Colas con garantía de entrega. Para implementar el Outbox sirve cualquier sistema de mensajería con acuse de recibo. Es importante que el identificador del mensaje sea estable entre entregas repetidas: resulta cómodo usarlo como base de la clave.
- API de gestión de proxy. Los servicios de proxy móvil de calidad tienen una interfaz programática que permite consultar el estado del canal, el tiempo hasta la rotación y cambiar la IP a demanda. Integrarse con esa API permite no empezar operaciones críticas antes de la rotación y cambiar de ruta entre intentos de forma consciente.
Del lado del servidor
- Base relacional con índices únicos. La opción más confiable para el almacén de claves, si los volúmenes lo permiten. La inserción con manejo de conflicto es una operación atómica de fábrica.
- Redis o similar. Para sistemas de alta carga: SET con flags NX y EX para la reserva, una clave aparte para la instantánea de la respuesta. Recuerda el riesgo de pérdida de datos al caer un nodo y configura la persistencia.
- Middleware de idempotencia. Para los frameworks web populares existen capas intermedias listas que implementan el contrato base: reserva, fingerprint, instantánea. Verifica cómo se comportan ante reintentos concurrentes y ante una caída entre ejecución y fijación: justo ahí se separan las buenas implementaciones de las formales.
- Gateways de API. Algunos gateways saben deduplicar por encabezado en la entrada. Eso quita carga a la aplicación, pero el gateway normalmente no conoce el resultado de negocio y puede cachear errores de infraestructura. Úsalo como primer filtro, no como única protección.
Pruebas
- Inyección de fallos de red. Herramientas de proxy para pruebas que saben cortar la conexión después de enviar la solicitud pero antes de la respuesta, retrasar la respuesta más allá del timeout, devolver 502 y 504. Sin esas pruebas no verás el comportamiento del sistema en el único escenario que importa.
- Pruebas concurrentes. Envío simultáneo de N solicitudes con una misma clave. Resultado esperado: exactamente una entidad creada, N-1 respuestas 409 o instantáneas. Cualquier otro resultado es un defecto.
- Prueba de reinicio en medio de la operación. Matar el proceso después de crear el pedido pero antes de fijar la clave. Verificar que el mecanismo de recuperación de registros colgados funcionó.
- Prueba de rotación. Primer intento por una IP, reintento por otra. Verificar que el servidor devolvió la instantánea y no rechazó el reintento por una heurística.
Estándares y documentos
El borrador de especificación del IETF sobre el encabezado Idempotency-Key es el punto de partida para formular el contrato: allí se definen el nombre del encabezado, la semántica de los conflictos y los códigos de respuesta recomendados. La documentación pública de los grandes proveedores de pago es un buen modelo de cómo describir un contrato para integradores externos: TTL, comportamiento ante desajuste del cuerpo, manejo de solicitudes concurrentes. La sección sobre métodos idempotentes en la especificación de semántica HTTP explica por qué se pueden repetir PUT y DELETE y no POST, y conviene releerla antes de diseñar endpoints.
Casos y resultados
Caso 1. Agregador de pedidos y 47 duplicados al mes
Una empresa agregadora pasaba pedidos al sistema de un socio logístico a través de un pool de proxies móviles con rotación cada cinco minutos. El volumen: unos 12 mil pedidos diarios. No había claves de idempotencia: la API del socio no las documentaba. Los duplicados se detectaban una vez al mes por conciliación financiera, y cada uno costaba en promedio 900 pesos entre cancelación, devolución y trabajo manual.
El diagnóstico con los logs del proxy mostró: el 0,4% de las solicitudes terminaba en corte de conexión después de enviar el cuerpo y antes de recibir la respuesta, sobre todo en los minutos de rotación. El reintento salía tres segundos después, y en el 30% de los casos la primera tentativa ya se había ejecutado para entonces. El cálculo coincidía con los duplicados observados.
Solución en tres pasos. Primero, se descubrió que la API del socio acepta el campo external_id y rechaza duplicados por él, aunque en la documentación aparecía en una sola línea. El campo empezó a llenarse con un identificador estable del Outbox local. Segundo, las ventanas de rotación se sincronizaron con el envío: quince segundos antes de la rotación no se enviaban pedidos nuevos. Tercero, se agregó conciliación cada diez minutos. Resultado del trimestre: cero duplicados, número de reintentos bajó 70% gracias a la sincronización con la rotación, y el tiempo promedio de pedido subió 1,2 segundos por esperar las ventanas: un precio aceptable.
Caso 2. Servicio de pagos y reintentos concurrentes
Un servicio fintech implementó idempotencia de su lado: se aceptaba el encabezado, la clave se guardaba en la base, y en el reintento se devolvía la instantánea. Aun así aparecían duplicados, raros pero regulares: aproximadamente uno cada 40 mil operaciones. La investigación mostró que la verificación de la clave se hacía con una lectura y luego con una escritura, y los clientes con timeouts agresivos (dos reintentos en un segundo por proxies distintos) caían en la ventana entre ambas.
Se reemplazó por una inserción con índice único y se agregó el estado in_progress con respuesta 409 y encabezado Retry-After de un segundo. Se añadió la métrica de reintentos concurrentes. Mostró algo inesperado: el 2% de todas las operaciones recibe al menos un 409, o sea que los clientes reintentan mucho más agresivamente de lo que se suponía. El servicio actualizó la documentación con recomendaciones de timeouts, y dos meses después la proporción de 409 bajó al 0,3%. Duplicados: cero en seis meses.
Caso 3. Integración con marketplace y lotes
Un vendedor cargaba stock y precios a un marketplace en lotes de 500 posiciones a través de proxy. La idempotencia del lote estaba a nivel de toda la solicitud. Ante un corte de conexión, el reintento o se rechazaba (lote en proceso) o devolvía la instantánea de un resultado parcial, de la que no se entendía qué posiciones se habían actualizado. El vendedor concluía "no se actualizó" y volvía a cargar, creando carreras entre el lote viejo y el nuevo.
Solución: pasar a lotes con identificadores de operación por elemento y pedir el estado por elemento tras una finalización indefinida. El tamaño del lote se redujo a 100 posiciones para que el tiempo de procesamiento no excediera el timeout. La cantidad de actualizaciones "colgadas" cayó de decenas por día a cero, y las discrepancias de stock, que antes causaban cancelaciones regulares de pedidos de compradores, desaparecieron.
Caso 4. Agente automatizado y reintentos en cadena
Tendencia de 2026: cada vez más integraciones las ejecutan agentes autónomos basados en grandes modelos de lenguaje, que llaman a las API siguiendo instrucciones. Un equipo implementó uno de esos agentes para compras a proveedores. Ante una respuesta indefinida, el agente "razonaba" y decidía repetir la operación, generando una solicitud nueva. No había claves, porque el agente formaba la llamada de cero cada vez. En la primera semana: 11 compras duplicadas.
Corrección: se le prohibió al agente formar solicitudes de creación directamente. Crea un registro de intención en el Outbox a través de una herramienta interna, y el envío lo hace un servicio determinista con claves y conciliación. El agente solo recibe el estado final. Los duplicados desaparecieron y, de paso, apareció una trazabilidad completa de quién y por qué inició cada compra. Conclusión general: los sistemas autónomos con capacidad de reintento son una fuente nueva y potente de duplicados, y la barrera de idempotencia para ellos es obligatoria.
FAQ: preguntas difíciles sobre idempotencia y reintentos
¿Hace falta una clave de idempotencia para PUT y DELETE, si por especificación son idempotentes?
Formalmente no: repetir un PUT con el mismo cuerpo dará el mismo estado. Pero hay matices. Si el PUT devuelve 201 al crear y 200 al actualizar, el reintento devolverá otro estado, y el cliente puede interpretarlo distinto. El DELETE en un reintento devolverá 404 en lugar de 204, lo que suele tratarse como error. La clave con instantánea de respuesta hace predecible el comportamiento. Además, si el PUT dispara efectos secundarios (envío de notificación, registro en auditoría), se ejecutarán de nuevo. La idempotencia del método no equivale a la idempotencia de todos los efectos secundarios.
¿Qué hacer si el servidor devolvió 409 in_progress y la primera tentativa en realidad murió?
Eso es responsabilidad del servidor: debe tener un mecanismo de recuperación de registros colgados con un umbral temporal. El cliente debería esperar el 409 un número limitado de veces (por ejemplo, hasta dos minutos), luego pasar la operación a unknown y enviarla a conciliación. Si el servidor sistemáticamente mantiene in_progress más de lo razonable, es un defecto de implementación que hay que reportar al dueño de la API.
¿Qué pasa con la clave si la solicitud pasa por varios proxies en cadena?
Nada especial: la clave va en el encabezado y atraviesa cualquier cadena de forma transparente. Lo único que conviene verificar es que ningún nodo intermedio elimine encabezados no estándar. Algunos gateways corporativos filtran encabezados por lista blanca. Prueba simple: enviar una solicitud por toda la cadena hacia tu propio endpoint de depuración y confirmar que el encabezado llegó.
¿Se puede usar el hash del cuerpo de la solicitud como clave y no guardar nada del lado del cliente?
Se puede, con reservas. Dos pedidos distintos con el mismo contenido (mismo producto, mismo monto, mismo comprador) obtendrán la misma clave y el segundo se rechazará como reintento. Para evitarlo, se agrega al cuerpo un componente único: identificador del carrito o número de secuencia local. Entonces el hash del cuerpo se vuelve una clave determinista de la operación. Es cómodo para clientes sin almacenamiento local confiable, pero exige una normalización estricta del cuerpo: cambiar el orden de los campos en JSON cambia el hash.
¿Cuánto esperar antes de reintentar para que el servidor termine el primer intento?
Es tema de la política de reintentos, pero desde el punto de vista del contrato importa una cosa: si el servidor soporta in_progress con 409, no hay que esperar "a ojo": el servidor mismo informará que la operación sigue en curso. Si el servidor no tiene ese estado, el intervalo antes del reintento debe superar el percentil 99 del tiempo de procesamiento de la operación en el servidor. Se puede averiguar en la documentación, en las métricas de solicitudes exitosas o empíricamente en un entorno de pruebas.
¿Conviene hacer idempotentes las operaciones de lectura?
GET es idempotente por definición, no necesita clave. Pero hay una excepción: la "lectura con efecto secundario", por ejemplo un GET que marca una notificación como leída o consume una cuota. Es un olor arquitectónico; esas operaciones es mejor convertirlas en POST con clave que añadir idempotencia a un GET.
¿Qué hacer con las claves al migrar o cambiar la versión de la API?
Incluye la versión del endpoint en el ámbito de la clave en el servidor. Así, una clave usada en v1 no chocará con la misma clave en v2. Para el cliente la regla es simple: la migración son operaciones nuevas con claves nuevas; las claves viejas no se trasladan. Si una operación estaba en unknown al momento de la migración, primero resuélvela por conciliación y luego migra.
¿Cómo explicarle al negocio por qué hay que gastar un sprint en idempotencia si "casi nunca hay duplicados"?
Calcula el costo de un duplicado: cancelación, devolución, soporte, reputación, a veces multas del socio. Multiplícalo por la frecuencia observada. Después muestra que la frecuencia crece de forma no lineal ante incidentes de red: en un día tranquilo, cero duplicados; en un día de avería del operador de telefonía, cientos en una hora. La idempotencia es un seguro con prima conocida y ganancia desconocida, pero potencialmente enorme. Además tiene un efecto colateral: permite reintentar solicitudes agresivamente sin miedo, lo que acelera la recuperación tras fallos.
¿Aumenta la idempotencia la carga sobre el servidor?
De forma insignificante: una escritura y una lectura adicionales por operación. En cambio, reduce la carga en escenarios de avería, porque el reintento devuelve la instantánea en milisegundos en lugar de reprocesar todo el pedido. Durante una tormenta de reintentos, un servidor con idempotencia aguanta mejor la carga que uno sin ella: es contraintuitivo, pero la práctica lo confirma.
Conclusión: contrato en lugar de esperanza
Reunamos lo esencial. Cualquier red entrega solicitudes bajo el principio de "al menos una vez". Los proxies, sobre todo los móviles, con rotación y canal de radio, hacen que los reintentos no sean rareza sino norma. La política de reintentos responde a la pregunta "cuándo y cómo reintentar". La idempotencia responde a la pregunta "por qué el reintento no romperá nada". Sin la segunda respuesta, la primera es peligrosa.
Un reintento seguro se sostiene sobre tres pilares. La clave de la operación, nacida antes del primer intento y viva en tu base, no en el cliente HTTP. El contrato del servidor con reserva atómica, estado in_progress, fingerprint del cuerpo, instantánea de respuesta y un TTL razonable. La conciliación como última línea de defensa para las operaciones atascadas en la incertidumbre. Si el servidor no da contrato, el rol de la clave lo toma un identificador natural, y el rol del almacén lo toma tu Outbox.
Qué hacer a continuación, hoy mismo:
- Encuentra en tus integraciones todas las operaciones POST que se repiten automáticamente. Para cada una responde: ¿hay clave, dónde se genera, coincide en los reintentos?
- Lee la documentación de las API de tus socios en busca de campos external_id y del encabezado Idempotency-Key. Verifica el comportamiento en el entorno de pruebas con dos solicitudes idénticas.
- Agrega el estado unknown al modelo de operaciones y un proceso de conciliación para él.
- Si eres dueño del servidor, corre tres pruebas: reintentos concurrentes, caída entre ejecución y fijación, reintento desde otra IP.
- Saca a un tablero la relación entre reintentos y operaciones únicas. Es tu indicador de salud del canal por proxy.
La idempotencia es un caso raro en el que la disciplina de ingeniería se convierte directamente en tranquilidad para el negocio. Un contrato diseñado una vez protege durante años de duplicados, tormentas de reintentos y llamadas nocturnas de contabilidad. Y, sinceramente, hay un placer particular en mirar una gráfica de miles de reintentos por un canal inestable y ver un cero firme en la columna de duplicados.