API Idempotency

La idempotencia puede aplicarse a una API asociando varios intentos con una misma intención de negocio. Una clave de idempotencia permite reconocer esos intentos; enviarla, por sí solo, no ofrece ninguna garantía.

Contrato práctico

El cliente conserva la misma clave al reintentar una intención y usa una nueva para una intención diferente. El servidor define el alcance de la clave —por ejemplo, cliente autenticado y operación— y compara los parámetros relevantes para rechazar su reutilización con otra solicitud.

La reserva de la clave y la aplicación del efecto necesitan coordinación que evite duplicados concurrentes. Si el efecto se persiste pero el resultado asociado no, un reintento puede volver a ejecutarlo. Cuando ambos viven en el mismo almacenamiento transaccional, una transacción puede cerrar esa ventana; un efecto externo necesita coordinación adicional.

El contrato también debe especificar qué ocurre con intentos en curso, fallos y respuestas repetidas. Un resultado incierto no equivale automáticamente a un intento que pueda reiniciarse de forma segura.

Límite temporal

La retención de claves define cuánto tiempo se reconoce una intención. Si el servidor olvida una clave, un reintento tardío puede aplicar un nuevo efecto. Ese límite debe ser compatible con la ventana de reintentos del cliente y con las consecuencias de duplicar la operación.

Esta práctica ayuda a ejecutar operaciones de forma confiable, pero no convierte cualquier workflow distribuido en una transacción ni garantiza efectos externos exactamente una vez.