Reintentos e idempotencia

Esta página explica cómo Midaz protege contra la duplicación con claves de idempotencia y cómo usarlas al reintentar una solicitud.

Cómo hacer seguros los reintentos

Las solicitudes fallidas a la API son comunes. Ocurre un tiempo de espera de red, o tu servicio se cae justo después de enviar una solicitud. Reintentar es natural, y necesitas estar seguro de que Midaz no procesará la misma operación dos veces. Al adjuntar una clave única a cada solicitud, le dices a Midaz: “Esta es la misma operación. Si ya la procesaste, no la vuelvas a procesar.” Midaz almacena esta clave temporalmente y la usa para determinar si la solicitud es nueva, está completa o aún está en curso. Esto protege tu sistema contra duplicados.

Idempotencia en Midaz

El encabezado X-Idempotency está disponible en todos los endpoints de creación de transacciones: en /v1, json, inflow, outflow, annotation, block y unblock; en /v2, direct, hold, block, unblock y batch. La reversión no recibe clave propia: Midaz deriva una.

Las demás APIs de Lerian usan sus propios encabezados de idempotencia, o ninguno. Esta página se centra en la idempotencia de la API del Ledger de Midaz.

Los endpoints de transacción commit y cancel usan un bloqueo basado en Redis para evitar el procesamiento concurrente de la misma transacción, pero no admiten idempotencia completa (sin respuestas en caché ni encabezado X-Idempotency-Replayed).

Para usarla, tu solicitud puede incluir dos encabezados:

X-Idempotency: la clave única que identifica la solicitud.
X-TTL: el tiempo de vida (en segundos) que Midaz debe almacenar esta clave en caché.

Si no envías el encabezado X-Idempotency, Midaz genera uno automáticamente calculando un hash SHA-256 del cuerpo de la solicitud. Por lo tanto, Midaz deduplica cuerpos de solicitud idénticos enviados a la misma organización y ledger.

Esto es lo que ocurre:

Cuando llega una clave nueva, Midaz la marca como pending, procesa la solicitud y almacena la respuesta completa en caché.
Si envías la misma clave otra vez dentro de la ventana del TTL:
1. Mientras la operación se ejecuta, Midaz devuelve un 409 Conflict (código de error 0084).
2. Si ya terminó y la solicitud coincide, Midaz devuelve exactamente la misma respuesta con un código de estado 201 Created y X-Idempotency-Replayed: true.
Si la transacción falla por errores de validación o saldo insuficiente, Midaz elimina la clave de idempotencia. Luego puedes corregir el problema y reintentar con la misma clave.

Midaz limita el alcance de las claves de idempotencia por organización y ledger. Por lo tanto, puedes usar el mismo valor de clave de forma independiente en distintas organizaciones o ledgers sin conflicto.

Resumen del flujo

La Figura 1 muestra el ciclo de vida completo de una solicitud idempotente:

Ciclo de vida completo de una solicitud idempotente en Midaz, desde la recepción de la clave de idempotencia hasta la devolución de la respuesta en caché o recién procesada — Figura 1. Ciclo de vida de una solicitud idempotente en Midaz.

Cómo funciona:

Si la solicitud no incluye una clave de idempotencia existente, Midaz crea una nueva, o la genera automáticamente a partir del hash del cuerpo de la solicitud. Luego Midaz procesa la solicitud, almacena la respuesta y la devuelve con X-Idempotency-Replayed: false.
Si la clave ya existe:
- Mientras la operación se ejecuta, Midaz devuelve un 409 Conflict.
- Si la operación está completa y la solicitud coincide, Midaz omite la ejecución y devuelve la respuesta en caché con un código de estado 201 Created y X-Idempotency-Replayed: true.
Si la solicitud original falló por errores de validación o de saldo, Midaz elimina la clave automáticamente. Puedes reintentar de forma segura con la misma clave.

Solicitud de ejemplo

Así se envía una solicitud idempotente para crear una transacción:

POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json HTTP/1.1
X-Idempotency: 7fb8e1d098cd4730bb932d038b3b8651
X-TTL: 60
Content-Type: application/json

{
  "description": "Monthly subscription payment",
  "code": "SUB-2025-001",
  "send": {
    "asset": "USD",
    "value": "1500",
    "source": {
      "from": [
        {
          "accountAlias": "customer-usd-1",
          "amount": {
            "asset": "USD",
            "value": "1500"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "merchant-usd-1",
          "amount": {
            "asset": "USD",
            "value": "1500"
          }
        }
      ]
    }
  }
}

Si la solicitud tiene éxito y la envías de nuevo dentro de 60 segundos, Midaz devolverá el resultado en caché con:

HTTP/1.1 201 Created
X-Idempotency-Replayed: true

Si la envías de nuevo mientras Midaz aún procesa la original, recibirás:

HTTP/1.1 409 Conflict

Generación de claves

Puedes proporcionar tu propia clave X-Idempotency o dejar que Midaz genere una automáticamente.

Generación automática de claves

Si omites el encabezado X-Idempotency, Midaz calcula un hash SHA-256 del cuerpo de la solicitud y lo usa como clave de idempotencia. Por lo tanto, Midaz deduplica el mismo cuerpo JSON exacto enviado a la misma organización y ledger. Esto es suficiente para la mayoría de los escenarios de reintento en los que el cuerpo de la solicitud no cambia entre intentos.

Generación de claves personalizadas

Usa una clave personalizada cuando necesites:

Correlacionar la clave de idempotencia con un ID de tu propio sistema (por ejemplo, un ID de pedido).
Reintentar con un cuerpo de solicitud modificado mientras sigues deduplicando (por ejemplo, después de corregir un campo).
Controlar el formato de la clave para fines de registro o auditoría.

La clave debe ser determinista: si reintentas la misma operación lógica, la clave permanece igual. Un enfoque común es usar un UUID o un hash basado en tu referencia interna:

import uuid

# Option 1: Use an existing business ID as the key
idempotency_key = f"order-{order_id}"

# Option 2: Generate a UUID and store it for retries
idempotency_key = str(uuid.uuid4())

Mejores prácticas

Siempre valida el encabezado `X-Idempotency-Replayed`

Cuando tu sistema recibe una respuesta de un endpoint de transacción, siempre verifica el encabezado de respuesta X-Idempotency-Replayed antes de procesar el resultado. Este encabezado te indica si la respuesta proviene de una operación nueva o de una repetición en caché:

X-Idempotency-Replayed: false: esta es una respuesta nueva. Midaz acaba de procesar la transacción.
X-Idempotency-Replayed: true: esta respuesta proviene de la caché. Midaz ya procesó la transacción.

No verificar este encabezado es un error de integración común. Sin esta verificación, tu sistema puede interpretar una respuesta repetida como una transacción nueva. Eso genera procesamiento duplicado de tu lado, aunque Midaz la haya ejecutado una sola vez.

Por ejemplo, si tu sistema liquida boletos (recibos bancarios) según las respuestas de transacción, debes verificar X-Idempotency-Replayed para evitar liquidar el mismo boleto dos veces.

Usa claves de idempotencia explícitas para flujos críticos

Aunque Midaz genera claves automáticamente a partir del cuerpo de la solicitud, para flujos financieros críticos (liquidaciones, pagos, transferencias), proporciona siempre una clave X-Idempotency explícita vinculada al ID de tu proceso de negocio. Esto te da:

Después de que la primera solicitud tiene éxito, un reintento con el cuerpo modificado dentro de la ventana del TTL recibe 409 (0084) en lugar de una segunda transacción.
Un registro de auditoría claro que vincula las transacciones de Midaz con tus operaciones internas.
Protección contra casos límite en los que la serialización de la solicitud podría diferir.

Establece valores de TTL adecuados

Elige valores de TTL que coincidan con tu ventana de reintento:

Para operaciones síncronas con reintentos rápidos: 60–120 segundos.
Para workflows asíncronos con posibles retrasos: 300–600 segundos.
Para procesamiento por lotes con ventanas de reintento largas: considera TTL más largos y claves explícitas.

Estrategia de reintentos

Usa estos patrones para diferentes escenarios de falla:

Fallas reintentables

Estas fallas son seguras de reintentar con la misma clave de idempotencia:

Escenario	Qué hacer
Tiempo de espera de red o error de conexión	Reintenta con la misma clave y el mismo cuerpo. Si la solicitud original fue procesada, recibirás la respuesta en caché.
Error `5xx` del servidor	Reintenta con backoff exponencial. El servidor puede estar sobrecargado temporalmente.
`409 Conflict` (`0084`), mismo cuerpo	Todavía no hay una respuesta almacenada para la clave. Reintenta después de un breve retraso.
Error de validación o de saldo	Corrige el problema en tu solicitud y luego reintenta con la misma clave de idempotencia (Midaz elimina la clave ante estas fallas).

Fallas no reintentables

Estas fallas requieren un enfoque diferente:

Escenario	Qué hacer
`400 Bad Request` (error de esquema)	Corrige el formato de la solicitud. No reintentes el mismo payload.
`401 Unauthorized` / `403 Forbidden`	Verifica tus credenciales de autenticación. Reintentar no ayudará.
`404 Not Found`	Verifica los IDs de organización, ledger o cuenta en la ruta de tu solicitud.

Backoff exponencial

Para errores transitorios, usa backoff exponencial con jitter para evitar sobrecargar el servidor:

import time
import random
import requests

def create_transaction_with_retry(idempotency_key, payload, max_retries=5, base_delay=1.0):
    """Retries with the same idempotency key on every attempt."""
    for attempt in range(max_retries):
        try:
            response = requests.post(
                f"{BASE_URL}/v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json",
                headers={
                    "X-Idempotency": idempotency_key,
                    "X-TTL": "300",
                    "Content-Type": "application/json",
                },
                json=payload,
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Una secuencia típica de reintentos con este patrón sería: 1s, 2s, 4s, 8s, 16s (más jitter aleatorio en cada intento).

Prevención de duplicación de entidades

Para algunos endpoints, no necesitas claves de idempotencia para evitar duplicados. Midaz aplica restricciones de unicidad en recursos críticos. Si intentas crear una entidad que entra en conflicto con una existente, el sistema bloquea la solicitud y devuelve un 409 Conflict con un error descriptivo:

Recurso	Campo único	Código de error
Ledger	Nombre (dentro de la organización)	`0002`
Asset	Nombre o código (dentro del ledger)	`0003`
Segment	Nombre (dentro del ledger)	`0015`
Account	Alias (dentro de la organización y el ledger)	`0020`
Account Type	Valor de la clave (dentro de la organización y el ledger)	`0108`

A diferencia de las claves de idempotencia, estas restricciones son permanentes y no expiran.

Idempotencia entre productos de Lerian

Las demás APIs de Lerian definen sus propios encabezados, alcances y señales de repetición de idempotencia, y algunas no admiten ningún encabezado de idempotencia. Consulta la referencia de la API del producto que llamas antes de reintentar un comando.

Preguntas frecuentes

¿Qué ocurre si no envío una clave de idempotencia?

Midaz genera una automáticamente calculando un hash SHA-256 del cuerpo de la solicitud. Por lo tanto, Midaz deduplica cuerpos de solicitud idénticos enviados a la misma organización y ledger. Solo necesitas proporcionar una clave personalizada si quieres controlar la deduplicación de forma independiente del cuerpo de la solicitud.

¿Puedo reutilizar una clave en diferentes organizaciones o ledgers?

Sí. Midaz limita el alcance de las claves de idempotencia por organización y ledger. El mismo valor de clave usado en distintas organizaciones o ledgers no genera conflicto. Sin embargo, dentro de la misma organización y ledger, cada clave debe ser única por operación.

¿Puedo reutilizar una clave en diferentes endpoints?

No. Usa una clave única para cada operación distinta.

¿Qué ocurre si cambio el TTL en un reintento?

Midaz solo usa el TTL de la primera solicitud. Cambiarlo después no tiene efecto.

¿La respuesta repetida siempre será idéntica?

Sí. Midaz repite la respuesta completa, incluidos el código de estado (201 Created) y el cuerpo, para las solicitudes completadas.

¿Cuál es el TTL predeterminado si no envío X-TTL?

La ventana predeterminada es de 300 segundos (5 minutos).

¿Qué ocurre si la solicitud original falla?

Si la transacción falla por errores de validación o saldo insuficiente, Midaz elimina la clave de idempotencia de la caché. Esto te permite corregir el problema y reintentar con la misma clave.

Resumen

Fundamentos de integración

Estabilidad y calidad

Diccionario de campos

Streaming de eventos

Reintentos e idempotencia

Cómo hacer seguros los reintentos

Idempotencia en Midaz

Resumen del flujo

Solicitud de ejemplo

Generación de claves

Generación automática de claves

Generación de claves personalizadas

Mejores prácticas

Siempre valida el encabezado `X-Idempotency-Replayed`

Usa claves de idempotencia explícitas para flujos críticos

Establece valores de TTL adecuados

Estrategia de reintentos

Fallas reintentables

Fallas no reintentables

Backoff exponencial

Prevención de duplicación de entidades

Idempotencia entre productos de Lerian

Preguntas frecuentes

​Cómo hacer seguros los reintentos

​Idempotencia en Midaz

​Resumen del flujo

​Solicitud de ejemplo

​Generación de claves

​Generación automática de claves

​Generación de claves personalizadas

​Mejores prácticas

​Siempre valida el encabezado X-Idempotency-Replayed

​Usa claves de idempotencia explícitas para flujos críticos

​Establece valores de TTL adecuados

​Estrategia de reintentos

​Fallas reintentables

​Fallas no reintentables

​Backoff exponencial

​Prevención de duplicación de entidades

​Idempotencia entre productos de Lerian

​Preguntas frecuentes

Cómo hacer seguros los reintentos

Idempotencia en Midaz

Resumen del flujo

Solicitud de ejemplo

Generación de claves

Generación automática de claves

Generación de claves personalizadas

Mejores prácticas

Siempre valida el encabezado `X-Idempotency-Replayed`

Usa claves de idempotencia explícitas para flujos críticos

Establece valores de TTL adecuados

Estrategia de reintentos

Fallas reintentables

Fallas no reintentables

Backoff exponencial

Prevención de duplicación de entidades

Idempotencia entre productos de Lerian

Preguntas frecuentes