Claves de idempotencia para operaciones de licencia seguras ante reintentos
Una escritura de licencia que agota el tiempo de espera te deja a ciegas: ¿se consumió el asiento o no? Si reintentas, arriesgas cobrar dos veces a un grupo de créditos o quemar un asiento dos veces; si te rindes, puedes haber vendido una licencia que nunca entregaste. Este es el problema de la respuesta perdida que afecta a todo cliente de licencias en red, y la solución es una clave de idempotencia que convierte un transporte de al-menos-una-vez en efectos de exactamente-una-vez. Así se mantienen correctas la activación, la medición, la emisión y la desactivación ante reintentos contra tu instancia autoalojada de Keyright.
La mayoría de los clientes de licencias se escriben como si la red funcionara o fallara de forma visible. No hace ni lo uno ni lo otro. El fallo que realmente te cuesta dinero es el que no puedes ver: una petición que llegó al servicio de emisión, hizo su trabajo —consumió un asiento, debitó un grupo de créditos, acuñó una licencia— y luego perdió su respuesta en el camino de vuelta. Una conexión TLS caída, un tiempo de espera de lectura del proxy inverso, un proceso de cliente que se reinició a mitad de la llamada: todos ellos dejan a quien llama con un tiempo de espera agotado y sin forma de saber si la operación ocurrió.
Si lo reintentas, podrías consumir el asiento dos veces, o debitar de nuevo los minutos del mismo trabajo de render, o emitir una segunda licencia para un solo pedido. Si te rindes, podrías haber cobrado a un cliente por una licencia que nunca entregaste. Este es el problema de la respuesta perdida, y es intrínseco a cualquier operación que cambie estado sobre un transporte poco fiable. La solución no es una red mejor. Es una clave de idempotencia: un identificador elegido por el cliente que permite al servidor reconocer un reintento como la misma operación lógica y reproducir el resultado original en lugar de ejecutarlo una segunda vez.
La ambigüedad, ilustrada
Considera una medición contra tu instancia autoalojada de Keyright. El cliente envía la medición, el servicio debita el grupo y confirma, y luego la respuesta nunca llega.
La segunda petición es byte a byte la primera, incluido su Idempotency-Key. Como el servidor registró el resultado bajo esa clave cuando confirmó el débito por primera vez, no vuelve a debitar: devuelve el MeterResult almacenado. El transporte entregó la petición dos veces; el grupo se movió una sola vez. Ese es todo el contrato: entrega al-menos-una-vez, efecto exactamente-una-vez.
La activación ya es idempotente — por sus propias entradas
Antes de recurrir a claves por todas partes, conoce lo que obtienes gratis. La activación de Keyright es idempotente por (clave de licencia, huella de la máquina). Reactivar la misma clave en la misma máquina devuelve la activación existente y su lease; no consume un segundo asiento. Las entradas son la identidad de deduplicación, así que el SDK puede reintentar por sí mismo un ActivateAsync que agotó su tiempo de espera sin ninguna cabecera extra.
var client = KeyrightClient.Initialize(new KeyrightOptions
{
Product = "acme-app",
PublicKeyBase64 = config["Keyright:PublicKey"], // solo verificación, no es un secreto
ServiceUrl = config["Keyright:ServiceUrl"], // tu instancia autoalojada
});
// Seguro de reintentar: el par (key, fingerprint) es la identidad natural de idempotencia.
LicenseInfo info = await Retry.OnTransient(() => client.ActivateAsync(userKey));
if (!info.IsValid)
return Gate.Deny(info.Reason); // falla en cerrado ante un rechazo real, no ante un timeout
La disciplina importante aquí es distinguir una activación rechazada (asientos agotados, clave revocada —un LicenseInfo real que debes respetar y no reintentar) de un fallo de transporte (timeout, 503 — reintenta). Más abajo haremos esa separación precisa.
Las operaciones que necesitan una clave explícita
No toda escritura se identifica por sí sola. Tres operaciones comunes no son idempotentes por sus entradas, a propósito, porque dos peticiones de aspecto idéntico suelen estar destinadas a ser dos efectos separados:
- Mediciones — dos llamadas
MeterAsync("render-minutes", 12)normalmente debitan 24. Hay que decirle al reintento de una sola medición que es un reintento. - Emisión desde la automatización de fulfillment — tu manejador de webhooks acuña una licencia cuando se paga un pedido. Un webhook reentregado no debe acuñar una segunda.
- Desactivación — liberar un asiento que ya liberaste debería ser un no-op, no un error.
Para estas, adjuntas una cabecera Idempotency-Key (el SDK la expone como parámetro donde corresponde). La clave es un identificador estable de la operación de negocio, elegido una vez y reutilizado en cada reintento de esa operación:
// El id del trabajo de render ES la clave natural — una medición por trabajo, siempre.
MeterResult draw = await Retry.OnTransient(
() => client.MeterAsync(pool: "render-minutes", amount: job.Minutes, idempotencyKey: job.Id));
if (!draw.Allowed)
return Gate.Deny("Minutos de render agotados. Recarga para continuar.");
Para la emisión impulsada por tu propia automatización, la operación es un POST HTTP a la API de administración y tú mismo pones la cabecera. Usa el id del pedido para que un evento de pago reentregado sea inofensivo:
POST /admin/licenses HTTP/1.1
Host: licensing.example.com
Authorization: Bearer {admin_token}
Idempotency-Key: order-2026-5591
Content-Type: application/json
{
"product": "acme-app",
"edition": "pro",
"seats": 5,
"customer": "cust_8e21",
"entitlements": ["export", "api"]
}
Un segundo POST que lleve Idempotency-Key: order-2026-5591 devuelve la misma licencia que creó la primera llamada —mismo id, mismo material de clave— sin acuñar una segunda licencia. Tu manejador de fulfillment queda seguro de llamar tantas veces como el sistema de comercio reentregue el evento.
Elegir la clave correctamente
La clave tiene exactamente dos trabajos, y es fácil equivocarse en ambos:
- La misma en todos los reintentos de una operación. Si generas un
Guid.NewGuid()nuevo en cada intento, cada reintento parece una operación nueva y el mecanismo no hace nada. Deriva la clave de la entidad de negocio (job.Id,order.Id), o genera un GUID una vez, persístelo junto a la operación y reutilízalo en cada reintento, incluso tras un reinicio del proceso. - Distinta entre operaciones genuinamente diferentes. Si un cliente ejecuta legítimamente dos trabajos de render, cada uno necesita su propia clave, o fusionarás dos cobros reales en uno. El id de negocio te da esto de forma natural; una constante compartida no.
Una regla útil: la clave debe ser tan duradera como la intención de la operación. Si la intención sobrevive a una caída —todavía le debes esa licencia al cliente— la clave también debe sobrevivir a la caída. Eso significa que pertenece a tu propio almacén (la fila del pedido, el registro del trabajo), escrita antes del primer intento.
Lo que el servidor impone, y por qué debería importarte
Una implementación correcta de idempotencia hace más que cachear una respuesta. Dos comportamientos te importan como quien llama:
La huella de la petición debe coincidir. El servidor registra un hash del cuerpo de la petición junto a la clave. Si llega una segunda petición con el mismo Idempotency-Key pero un cuerpo distinto —digamos, seats: 5 la primera vez y seats: 50 la segunda— eso es un error por tu parte, no un reintento, y el servicio lo rechaza con 409 Conflict en lugar de honrar silenciosamente cualquiera de los dos. Trata un 409 aquí como “reutilizaste una clave para una operación distinta” y corrige el punto de llamada; nunca lo tapes rotando la clave.
Los duplicados concurrentes se serializan. Si dos copias de la misma petición están en vuelo a la vez (un cliente reintentó antes de que se perdiera la respuesta del primer intento, y ambas aterrizan), el servicio deja que la primera se complete y responde la segunda desde el resultado almacenado —o, si la primera sigue en marcha, devuelve una señal reintentable para que el duplicado retroceda en lugar de ejecutarse en paralelo. No tienes que coordinar esto entre tus propios procesos; la clave lo hace.
Una política de reintentos que solo reintenta lo seguro
Las claves de idempotencia hacen que los reintentos sean seguros; no deciden cuándo reintentar. Combínalas con una política que reintente los fallos de transporte y deje en paz los rechazos de negocio. Con Polly:
var transient = new ResiliencePipelineBuilder()
.AddRetry(new RetryStrategyOptions
{
MaxRetryAttempts = 4,
BackoffType = DelayBackoffType.Exponential,
UseJitter = true, // reparte los reintentos, evita una estampida
ShouldHandle = new PredicateBuilder()
.Handle<HttpRequestException>() // conexión caída
.Handle<TaskCanceledException>() // timeout
.HandleResult<HttpResponseMessage>(r =>
r.StatusCode == HttpStatusCode.ServiceUnavailable // 503
|| r.StatusCode == HttpStatusCode.GatewayTimeout // 504
|| (int)r.StatusCode == 429), // limitado: retrocede
})
.Build();
La línea que hay que mantener es esta: reintenta 429, 503, 504 y los fallos de conexión en crudo; no reintentes 400, 401, 403, 404, 409 ni un LicenseInfo válido-pero-rechazado. El primer grupo es “la operación puede o no haber ocurrido” —exactamente donde la clave de idempotencia te protege. El segundo grupo son respuestas definitivas; reintentarlas solo martillea el servicio con una petición que seguirá siendo rechazada. Un 409 de un endpoint de idempotencia es especial, como se señaló: significa clave reutilizada con un cuerpo distinto, lo cual es un defecto de código, no algo que reintentar.
Por último, mantén la puerta fallando en cerrado ante los rechazos y operativa ante fallos ante los errores de transporte para los que has agotado los reintentos. Una medición que no puede alcanzar el servicio tras cuatro intentos debería recurrir al lease cacheado y su ventana de gracia —no denegar a un cliente que paga por un bache— mientras que una medición que el servicio rechazó activamente (grupo vacío) permanece denegada. La clave de idempotencia es lo que hace inofensivos los reintentos intermedios.
Lista de verificación
- Activación y revalidación: apóyate en la idempotencia
(key, fingerprint); reintenta los timeouts directamente. - Medición, emisión, desactivación: adjunta un
Idempotency-Keyderivado del id de negocio (job.Id,order.Id). - Elige la clave una vez, persístela con la operación, reutilízala en cada reintento, incluso tras un reinicio.
- Nunca generes una clave nueva por intento; nunca reutilices una clave ya resuelta para una operación distinta.
- Reintenta solo
429/503/504/errores de conexión; honra los4xxy elLicenseInforechazado como finales. - Trata un
409 Conflictde un endpoint de idempotencia como un error de misma-clave/cuerpo-distinto en el punto de llamada. - Mantén los reintentos bien dentro de la ventana de retención de claves del servidor.
Nada de esto aparece en el camino feliz, que es precisamente por lo que hay que diseñarlo en lugar de descubrirlo. El transporte entregará algunas de tus escrituras de licencia más de una vez; con una clave de idempotencia en cada llamada que cambia estado, tus asientos, tus grupos de créditos y tus licencias emitidas se mueven exactamente una vez de todos modos.
Prueba Nebula.NET
Endurece tu código .NET en minutos — empieza con la edición gratuita.