Una API recibe una solicitud para crear una orden, la guarda y pierde la conexión antes de responder. El cliente no sabe si la operación terminó. Si repite la petición como una creación nueva, puede generar otra orden.
Una clave de idempotencia permite reconocer que ese segundo intento pertenece a la misma operación lógica. Para que funcione, cliente y servidor deben acordar algo más que el nombre de una cabecera: el ámbito de la clave, qué solicitud representa, cómo se guarda el resultado y qué ocurre si el proceso se interrumpe.
Esta guía plantea un diseño para una API de órdenes. Los estados y respuestas son propuestas ilustrativas, no el contrato de una API existente de Nexeus Big Data.
La clave identifica la intención, no el intento de conexión
El cliente genera una clave antes del primer envío y la conserva mientras reintenta esa operación. Si crea una nueva clave en cada reconexión, el servidor verá solicitudes distintas.
También puede ocurrir el error contrario: reutilizar siempre la misma clave para cualquier orden de una pantalla. La siguiente operación legítima podría confundirse con la anterior.
Una regla útil es vincular la clave al comando de negocio pendiente. La aplicación cliente conserva su relación con el contenido y con el estado de entrega. Al recibir un resultado confirmado, cierra ese comando; una nueva intención tendrá otra identidad.
No utilices datos personales como parte visible de la clave. La identidad del usuario y su autorización se comprueban por el mecanismo de acceso de la API. La clave no sustituye una credencial.
Define el ámbito en el que debe ser única
En una API con varias organizaciones, la misma cadena no debería permitir recuperar el resultado de otra organización. El servidor puede delimitar la identidad mediante organización autorizada, operación y clave.
Por ejemplo, la unicidad puede recaer sobre:
(tenant_id, operation_name, idempotency_key)El servidor obtiene la organización del contexto autenticado y verifica permisos en cada petición. No acepta sin más un identificador enviado por el cliente para decidir qué resultado devolver.
Decide también si la clave cubre una versión concreta de la operación. Cuando cambia el significado del comando, reutilizar una clave antigua sin verificar el contrato puede producir respuestas difíciles de interpretar.
Asocia la clave a una huella de la solicitud
Si el cliente envía la misma clave con otro producto o cantidad, no se trata del mismo reintento. La API debe detectar el conflicto y ofrecer una respuesta documentada, en lugar de ignorar el cambio.
Una huella puede calcularse sobre una representación normalizada de los campos que determinan la operación. Normalizar exige reglas: orden de propiedades, tratamiento de valores ausentes, números y campos por defecto. El objetivo es evitar que dos representaciones equivalentes se consideren diferentes sin ocultar diferencias significativas.
No incluyas un identificador de trazabilidad que cambia en cada intento si no modifica la intención de negocio. Sí debes incluir un campo como la moneda cuando altere el significado del importe.
La API de Stripe documenta su uso de claves de idempotencia, la conservación de resultados y la comparación de parámetros para detectar reutilizaciones incompatibles. Es un ejemplo de contrato explícito; sus reglas concretas no se transfieren automáticamente a otra API.
El registro debe sobrevivir al proceso que atiende la petición
Guardar la clave solo en memoria no protege frente a un reinicio ni frente a varias instancias atendiendo solicitudes. El diseño necesita almacenamiento compartido con las garantías de concurrencia apropiadas.
Un registro ilustrativo puede incluir:
| Campo | Finalidad |
|---|---|
| Ámbito y clave | Identificar la operación lógica |
| Huella de solicitud | Detectar cambios de intención |
| Estado | Distinguir en curso, confirmada o pendiente de reconciliación |
| Referencia de resultado | Encontrar la orden creada y su respuesta |
| Fechas operativas | Gestionar seguimiento y conservación |
| Identificador de ejecución | Relacionar trazas y recuperación |
El resultado puede guardarse directamente o reconstruirse desde un recurso estable, siempre que la respuesta cumpla el contrato. Si la API promete repetir el resultado original, reconstruirlo desde una orden modificada después puede incumplir esa promesa.
Aplica a este almacenamiento controles de acceso y conservación. Una respuesta de API puede contener información que no debería aparecer íntegra en registros de diagnóstico.
Dos peticiones simultáneas necesitan una decisión atómica
Un patrón incorrecto consiste en consultar si existe la clave y, si no existe, ejecutar la operación. Dos instancias pueden hacer la consulta antes de que ninguna guarde el registro.
La reserva debe apoyarse en una operación atómica y una restricción de unicidad o garantía equivalente. Solo una ejecución obtiene el derecho a comenzar. La otra consulta el estado y sigue la política prevista: esperar de forma acotada, recibir una referencia para consultar el progreso o reintentar después.
Si la creación de la orden y el registro de idempotencia viven en la misma base de datos, una transacción puede relacionar sus cambios. El orden exacto depende del modelo y de cómo se recuperen transacciones fallidas. Hay que ensayar el fallo en cada punto; no basta con que el camino sin errores funcione.
Una reserva abandonada no significa necesariamente que la operación nunca ocurrió. Antes de liberar una clave para ejecutarla otra vez, se debe determinar qué efectos se confirmaron.
Cuando hay un sistema externo, aparece un resultado incierto
Supongamos que, además de guardar la orden, la API solicita un servicio a un proveedor. Puede perderse la conexión después de que el proveedor acepte la solicitud. La transacción local no puede deshacer por sí sola ese efecto externo.
Si el proveedor acepta claves de idempotencia, conserva y reutiliza la identidad correspondiente al reintentar esa llamada. Si permite consultar la operación mediante una referencia estable, utiliza esa consulta para reconciliar el resultado.
Cuando no existe ninguna de esas capacidades, el diseño puede necesitar revisión manual o una operación compensatoria autorizada. Repetir a ciegas no convierte la integración en segura. El estado pendiente de reconciliación debe poder observarse y tener un responsable.
Un patrón de salida transaccional puede ayudar a registrar juntos el cambio local y el trabajo pendiente de enviar. Aun así, el consumidor debe gestionar entregas repetidas y el efecto en el destino. La clave forma parte de la solución, no es una promesa universal de ejecución única entre sistemas.
Caducar la clave cambia las garantías
La conservación debe cubrir el periodo de reintento acordado y las necesidades de recuperación. Si se elimina el registro y el cliente repite una petición antigua, el servidor puede interpretarla como nueva.
Documenta esa frontera. El cliente necesita saber cuándo dejar de reintentar y cómo consultar el estado de una operación cuyo resultado desconoce. La política puede exigir una referencia de negocio única adicional para impedir duplicados más allá de la vida de la clave.
No elijas el plazo copiando el de otro proveedor. Depende de colas, operaciones desconectadas, integraciones y tiempos de resolución que tu sistema realmente admite.
Pruebas que deben pasar antes de publicar la API
Ensaya al menos estas situaciones: mismo contenido y clave repetidos; misma clave con contenido diferente; dos peticiones simultáneas; reinicio tras reservar; fallo después de guardar la orden; respuesta perdida del proveedor; reintento tras caducar y cambio de permisos entre intentos.
En cada caso comprueba tanto la respuesta HTTP como los recursos creados y las acciones externas confirmadas. Un mensaje de éxito repetido no demuestra que no existan duplicados en el destino.
Relaciona estas pruebas con la idempotencia de pipelines de datos cuando la API alimente procesos analíticos: ambas capas deben conservar la identidad de la operación sin confundirla con la identidad del lote.
Si estás definiendo un backend para un producto de datos, comparte con Nexeus Big Data las operaciones que producen efectos y sus escenarios de fallo. Ese inventario permite concretar qué garantía de reintento puede ofrecer la API y cómo demostrarla.