La respuesta breve

La idempotencia, los reintentos y la conciliación no son tres funciones independientes. Forman una sola cadena de gestión de fallos: los identificadores estables reconocen la misma intención de negocio; la semántica de idempotencia determina si la repetición es segura; los reintentos acotados gestionan fallos transitorios; la conciliación compara las solicitudes con el resultado financiero final; y la escalación manual gestiona estados que la automatización todavía no puede resolver.

La suposición más peligrosa es «un tiempo de espera significa fallo, así que envíelo de nuevo». Un servidor puede completar una solicitud aunque su respuesta se pierda durante la transmisión. El sistema que llama queda entonces en un estado desconocido, no ante un fallo confirmado. Sin semántica explícita de idempotencia o de consulta, un reintento automático puede crear una sesión, transferencia o asiento contable duplicado.

Cinco conceptos que deben separarse

Concepto Definición operativa Lo que no garantiza por sí solo
Identificador estable Un valor duradero que correlaciona la misma solicitud, transacción, ronda o apuesta La presencia de un ID no demuestra deduplicación del lado del servidor
Idempotencia Se espera que repetir la misma intención de negocio tenga el mismo efecto final que procesarla una vez Las respuestas no tienen que ser textualmente idénticas y la solicitud aún puede fallar
Reintento Otro intento dentro de condiciones definidas, límites de intentos y un presupuesto de tiempo Un error permanente no se convierte en éxito, y el reintento no sustituye la consulta de estado
Conciliación Comparación de la intención de solicitud, el resultado de negocio, los registros de transacción o ronda y el efecto en el libro mayor No decide automáticamente toda compensación
Escalación manual Una persona autorizada investiga y decide cuando la automatización no puede concluir con seguridad El juicio humano no puede compensar registros o definiciones de protocolo faltantes

Los métodos HTTP no determinan la semántica de negocio del proyecto. RFC 9110 define PUT, DELETE y los métodos seguros como idempotentes, y advierte a los clientes que no reintenten automáticamente solicitudes no idempotentes salvo que su semántica real sea conocida como idempotente o que el cliente pueda establecer que la solicitud original no se aplicó. Las llamadas de plataforma mostradas en la referencia pública de la API usan POST, por lo que el comportamiento seguro de reintento no puede inferirse solo a partir del método HTTP.

1. Identificadores estables: separe el rastreo de la identidad de negocio

Un diseño fiable normalmente necesita al menos dos clases de identificadores:

  • ID de trazabilidad de solicitud: correlaciona un intento de transporte con registros, una respuesta y material de diagnóstico.
  • ID de transacción de negocio: identifica una intención de negocio y correlaciona transferencias, movimientos del libro mayor, rondas o apuestas.

La referencia pública de la API muestra reqTraceId y, en algunos flujos de transacción, campos como merchantTransactionId, transactionId, roundId y betId. Describe merchantTransactionId como un identificador único de transacción del comerciante que puede respaldar la conciliación de registros.

Estos campos proporcionan indicios de trazabilidad. No establecen comportamientos no confirmados, como si cada operación se deduplica, el alcance y período de retención de la deduplicación, qué ocurre cuando llega el mismo ID con parámetros distintos o si una repetición devuelve el resultado original. Estas semánticas requieren un protocolo formal y pruebas en el entorno aplicable.

El borrador de IETF draft-ietf-httpapi-idempotency-key-header-07 propuso un encabezado Idempotency-Key. A fecha de 9 de agosto de 2026, esa versión estaba caducada y archivada y no se había convertido en una RFC. Solo puede tratarse como un antecedente histórico de diseño, no como un estándar vigente, un protocolo de AG ni evidencia de que AG admita ese encabezado.

2. Reintentos: realice intentos acotados solo para operaciones y fallos seguros

Un reintento automático debe cumplir ambas condiciones: el fallo se clasifica como transitorio y la repetición es segura conforme al protocolo aplicable.

Escenario Principio predeterminado Condición antes de un reintento automático
Consulta o lista de solo lectura Puede considerarse un reintento acotado El protocolo confirma que no hay efecto secundario y el fallo es transitorio
Creación de sesión No la vuelva a crear solo por un tiempo de espera Idempotencia explícita, o consulta de la sesión existente por su identificador original
Modificación de monedero o transferencia Consulte el estado o concilie primero por defecto Se confirman el ID de negocio, el alcance de idempotencia y el comportamiento ante respuestas duplicadas
Procesamiento de callbacks El consumidor debe detectar eventos repetidos Ambas partes acuerdan el ID estable de evento o transacción utilizado para deduplicar
Error de parámetro, permiso o firma No reintente automáticamente la misma solicitud Corrija el parámetro, acceso, reloj o credencial y tome una nueva decisión
Tiempo de espera o desconexión Marque el resultado como desconocido Consulte primero por el ID original; reintente solo cuando se haya establecido una semántica segura

Los reintentos necesitan un tiempo de espera por intento, un número máximo de intentos, un presupuesto total de tiempo y condiciones de parada. Este artículo no prescribe valores numéricos: dependen de la semántica de la API, las restricciones ascendentes, el riesgo de negocio y el acuerdo entre las partes.

3. Backoff exponencial con jitter: evite presión sincronizada

Cuando un fallo transitorio se puede reintentar con seguridad, el backoff exponencial con jitter aleatorio y acotado puede distribuir los intentos a lo largo del tiempo. Conceptualmente, el retraso aumenta con cada intento hasta un máximo, mientras que el jitter evita que muchos clientes reintenten en el mismo instante.

Tanto AWS como Google documentan el valor del backoff y el jitter. Google también deja claro que la elegibilidad para reintentar depende de que el fallo sea reintentable y la operación sea idempotente. Un algoritmo de backoff no puede hacer segura una escritura no idempotente y no sustituye un presupuesto global de reintentos.

Evite estos antipatrones:

  • bucles de reintento inmediatos o sin límite;
  • una política de reintento para todos los errores HTTP y de negocio;
  • reintentos en las capas de gateway, SDK, servicio y cola que se multiplican entre sí;
  • generar un nuevo ID de transacción de negocio para cada intento, lo que impide reconocer la intención original;
  • registrar claves, credenciales completas o datos sensibles innecesarios durante los reintentos;
  • continuar los reintentos automatizados indefinidamente después de fallos repetidos.

RFC 9110 también exige cautela con los reintentos automatizados; un fallo repetido no debe convertirse en una repetición sin límite.

4. Estado desconocido: no renombre la incertidumbre como fallo

Cuando una solicitud ha salido del sistema que llama, pero no llega un resultado de negocio completo, utilice un estado UNKNOWN independiente. Un flujo neutral respecto al protocolo puede representarse así:

NEW -> SENT -> CONFIRMED_SUCCESS
            -> CONFIRMED_FAILURE
            -> UNKNOWN -> QUERY_OR_RECONCILE -> CONFIRMED_SUCCESS
                                           -> CONFIRMED_FAILURE
                                           -> MANUAL_REVIEW

En UNKNOWN, consulte resultados existentes, registros de transacciones o movimientos del libro mayor mediante el ID de solicitud o de transacción de negocio original. Si el protocolo no dispone de una ruta de consulta autorizada, detenga las acciones automatizadas que podrían duplicar efectos, conserve el contexto y escale. No suponga un fallo.

Las etiquetas de estado, la API de consulta y los estados terminales deben seguir el protocolo de las partes. Este diagrama es un método de diseño; no afirma que AG implemente estos estados exactos.

5. Conciliación: utilice varios registros para establecer el efecto final

La conciliación es más que comparar dos valores de saldo. Para flujos de monedero, apuesta o ganancia, correlacione al menos:

  • la intención de negocio original y el ID de trazabilidad de solicitud;
  • el ID de transacción de negocio del comerciante o de la plataforma;
  • los identificadores de transacción, ronda y apuesta de la contraparte;
  • el importe, la moneda, la dirección y la interpretación temporal;
  • el resultado de negocio de la API y los registros posteriores;
  • el movimiento del libro mayor, el saldo actual y el estado final de procesamiento.

Los resultados útiles incluyen conciliado, fallo confirmado, duplicado, discrepancia de importe o moneda, registro faltante y estado desconocido. Cada discrepancia necesita un responsable predefinido, un conjunto de evidencias, autoridad de compensación y una condición de cierre. No reenvíe la mutación financiera original como sustituto de la conciliación de registros.

La frecuencia, retención y tolerancia dependen del riesgo de negocio, el volumen, el modelo de monedero y el contrato. Este artículo no establece períodos ni umbrales fijos de AG.

6. Cuándo es obligatoria la escalación manual

Detenga la automatización y abra una revisión manual auditable cuando se cumpla cualquiera de estas condiciones:

  • se agota el presupuesto de reintentos acotados y el estado de negocio sigue siendo desconocido;
  • un ID de negocio aparece con importes, monedas, cuentas u otros parámetros críticos distintos;
  • el resultado de la solicitud, el registro de transacción y el movimiento del libro mayor entran en conflicto;
  • no se encuentra el registro autorizado definido por el protocolo, o faltan registros críticos;
  • existe sospecha de débito duplicado, pago duplicado, acceso no autorizado o incidente de seguridad;
  • la compensación automatizada podría incrementar el impacto financiero, de cumplimiento normativo o sobre el cliente.

El registro debe incluir los ID originales, una cronología, las acciones ya realizadas, la evidencia, la evaluación de riesgo, el aprobador y el resultado final del cierre. Los secretos y las credenciales no pertenecen al cuerpo de los tickets.

Lista de verificación de implementación en una página

  • Defina ID estables por separado para el rastreo de solicitudes y las transacciones de negocio.
  • Especifique el alcance de idempotencia, el comportamiento ante conflictos y la semántica de respuesta repetida para cada operación con efectos secundarios.
  • Separe los errores transitorios, los errores permanentes y los estados desconocidos.
  • Reintente automáticamente solo cuando se confirme que la repetición es segura.
  • Establezca tiempos de espera, presupuesto total, un límite de backoff exponencial acotado y jitter para las rutas elegibles.
  • Impida que los reintentos en varias capas del sistema se multipliquen inesperadamente.
  • Proporcione consulta o conciliación por el ID original para estados desconocidos.
  • Concilie la evidencia de transacción, ronda, importe, moneda y libro mayor.
  • Defina las condiciones de parada de la automatización y la responsabilidad de la escalación manual.
  • Pruebe en staging los casos de tiempo de espera, respuesta perdida, envío duplicado y discrepancia de registros.

Lo que actualmente puede evaluarse en este sitio

  • La referencia pública de la API muestra identificadores para solicitudes y algunas transacciones, rondas y apuestas de negocio.
  • Las notas de la interfaz exigen evaluar el resultado de negocio del cuerpo de la respuesta en lugar de basarse únicamente en el estado HTTP.
  • Las consultas de monedero, transacción, ronda y apuesta pueden orientar el diseño de pruebas de trazabilidad y conciliación.
  • Las páginas actuales describen monederos únicos y de transferencia, pero el diseño de fiabilidad debe seguir el modelo de monedero seleccionado y el protocolo formal.

Límites que conviene tener presentes

  • Esta página no afirma que todos los endpoints POST de AG sean idempotentes ni que AG admita el encabezado Idempotency-Key.
  • No inventa el alcance de deduplicación, la retención, las respuestas ante conflictos, los recuentos de reintentos, los parámetros de backoff ni los calendarios de conciliación de AG.
  • No añade ningún endpoint de consulta, compensación, estado o producción.
  • No promete cero duplicados, cero pérdidas, coherencia absoluta, seguridad absoluta, rendimiento fijo ni un SLA.
  • Los ejemplos de la API pública no constituyen un protocolo de producción, una garantía de tiempo de ejecución ni un registro de admisión en producción para un proyecto.

Preguntas frecuentes

¿Se puede reintentar automáticamente una solicitud POST fallida?

No a partir de «fallida» o POST por sí solos. Establezca primero si el fallo es transitorio, si la solicitud original ya pudo surtir efecto y si el protocolo formal proporciona idempotencia o consulta por el ID original. De lo contrario, la operación pertenece al manejo de estado desconocido y la conciliación de registros.

¿Un tiempo de espera significa que la transacción falló?

No. Un tiempo de espera solo indica que el sistema que llama no recibió un resultado completo a tiempo. El servidor puede no haber comenzado, seguir procesando o haber tenido éxito o fallado. Consulte o concilie mediante el ID de negocio original.

¿Un ID de transacción único demuestra idempotencia?

No. Es una base importante para reconocer una intención de negocio, pero el protocolo también debe definir cómo el servicio lo almacena y compara, su alcance y duración, los conflictos de parámetros y el resultado que devuelve ante una repetición.

¿Un reintento debe recibir un nuevo ID de solicitud?

Depende de cómo el protocolo separa una intención de negocio de un intento de transporte. Por lo general, el ID de transacción de negocio debe permanecer estable. Que se reutilice o derive un ID de trazabilidad debe quedar explícito en el contrato de interfaz, no inferirse de este artículo ni del nombre de un campo.

Lecturas relacionadas y próximos pasos

Para diseñar la fiabilidad de una integración específica, use la sección «Contáctenos» para proporcionar el modelo de monedero, la dirección de llamada, las operaciones de negocio críticas y las capacidades actuales de conciliación. AG podrá entonces confirmar los identificadores, la semántica de consulta, los límites de reintento y la responsabilidad de escalación conforme al protocolo formal, sin prometer por adelantado comportamiento de producción.

Fuentes y alcance

Los campos pertinentes y el alcance de las páginas aparecen en la referencia pública de la API, descripción general de la API de Slots y proceso de integración. La implementación todavía debe seguir el protocolo y el comportamiento del entorno observado acordado por ambas partes.

Fuentes generales de fiabilidad:

Estas fuentes explican patrones generales. No confirman que AG utilice el algoritmo, los parámetros o el encabezado de ningún proveedor. Los responsables de API, monedero, SRE, seguridad y conciliación deben revisar la semántica del proyecto y los campos de ejemplo.

¿Quiere convertir esta guía en un plan de proyecto?

Esta guía apoya la evaluación y no sustituye la validación técnica, contractual, de certificación ni de requisitos locales.

Contactar