Reintentos e idempotencia

Usa claves de idempotencia para evitar operaciones duplicadas en los endpoints de transacción de Midaz al reintentar fallas transitorias, tiempos de espera de red y respuestas 5xx.

Midaz garantiza que las operaciones sean seguras de reintentar y nunca se procesen más de una vez.

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

---

Midaz usa claves de idempotencia para garantizar que las operaciones de transacción sean seguras de reintentar y nunca se procesen más de una vez. Este mecanismo está disponible en todos los endpoints de transacción: /transactions/json, /transactions/dsl, /transactions/inflow, /transactions/outflow, /transactions/annotation y /transactions/{id}/revert.

Otros productos de Lerian también admiten idempotencia mediante sus propios encabezados. Consulta la sección Idempotencia entre productos de Lerian más abajo. 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:

1. Cuando llega una clave nueva, Midaz la marca como pending, procesa la solicitud y almacena la respuesta completa en caché.
2. 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) con X-Idempotency-Replayed: false.
   2. Si ya terminó, Midaz devuelve exactamente la misma respuesta con un código de estado 201 Created y X-Idempotency-Replayed: true.
3. 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. Otros productos de Lerian usan estrategias de alcance diferentes. Consulta la tabla comparativa para más detalles.

​

Resumen del flujo

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

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 con X-Idempotency-Replayed: false.
  • Si la operación está completa, 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:

HTTP

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

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

HTTP/1.1 409 Conflict
X-Idempotency-Replayed: false

​

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:

Python

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:

• Control total sobre la deduplicación, incluso si el cuerpo de la solicitud cambia ligeramente entre reintentos.
• 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 con X-Idempotency-Replayed: false	La solicitud anterior aún se está procesando. Espera y 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:

Python

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

---

Varios productos de Lerian admiten idempotencia, cada uno con su propia convención de encabezado. La mayoría de los productos devuelven el encabezado de respuesta X-Idempotency-Replayed para indicar si la respuesta repite un resultado en caché. Midaz siempre incluye este encabezado (false para solicitudes nuevas, true para repeticiones), mientras que otros servicios solo lo agregan cuando la respuesta es una repetición. La ausencia del encabezado significa una solicitud nueva. Direct Pix no devuelve este encabezado.

Producto	Encabezado de solicitud	Acepta X-TTL	X-Idempotency-Replayed	Alcance	Endpoints cubiertos
Midaz	X-Idempotency	Sí (300s por defecto)	Siempre (false/true)	Por organización y ledger	Creación, anotación y reversión de transacciones (6 endpoints)
Matcher	X-Idempotency-Key (también acepta Idempotency-Key)	No	Solo en repeticiones	Por tenant, método y ruta	Todos los endpoints POST/PUT/PATCH (~33 endpoints mediante middleware global). Los endpoints de callback usan un patrón de readquisición tras fallo: si un callback anterior con la misma clave falló, Matcher vuelve a adquirir el bloqueo automáticamente y reprocesa la solicitud. Consulta Webhooks y callbacks para más detalles. Las claves deben contener entre 1 y 128 caracteres: letras, dígitos, guiones, guiones bajos o dos puntos. Las claves inválidas se rechazan con MTCH-0015 (400). Si una solicitud con la misma clave sigue en curso, Matcher devuelve MTCH-0018 (409): espera a que termine y luego reintenta con la misma clave. Consulta la lista de errores de Matcher para todos los códigos de error de idempotencia.
TED	X-Idempotency-Key	No	Solo en repeticiones	Por clave de idempotencia (sin alcance por tenant)	Envío, devolución y cancelación de mensajes (3 endpoints)
Indirect Pix	X-Idempotency	Sí	Solo en repeticiones	Por cuenta	Inicio de cashout, procesamiento de cashout y devolución (3 endpoints)
Direct Pix	Idempotency-Key	No	No	Por clave	Creación de pago e inicio de devolución (2 endpoints)
Reporter	X-Idempotency	No	Solo en repeticiones	Por clave	Creación de informes y plantillas (2 endpoints)

Midaz siempre incluye el encabezado X-Idempotency-Replayed en la respuesta (false para solicitudes nuevas, true para repeticiones). Otros servicios (Matcher, TED, Indirect Pix y Reporter) solo agregan este encabezado cuando la respuesta es una repetición. La ausencia del encabezado significa una solicitud nueva. Direct Pix no devuelve este encabezado. Su middleware de idempotencia repite la respuesta completa de forma transparente, sin indicador de repetición.

Fees Engine, Tracer, Auth y CRM actualmente no admiten encabezados de idempotencia. En cambio, las validaciones de Tracer son idempotentes mediante requestId. POST /v1/validations deduplica según el campo del cuerpo y devuelve el resultado en caché con HTTP 200 (HTTP 201 en la primera llamada). Las operaciones de token de Auth son inherentemente idempotentes. Las entidades de CRM y de onboarding dependen de restricciones de unicidad en su lugar.

​

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?

Midaz limita el alcance de las claves de idempotencia por organización y ledger, no por endpoint. Si reutilizas la misma clave en un endpoint diferente dentro de la misma organización y ledger, recibirás la respuesta en caché del endpoint original. Usa siempre claves únicas 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), los encabezados 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.