Claves de idempotencia

Una clave de idempotencia es una etiqueta única que tu sistema adjunta a una solicitud de escritura para que Mono pueda reconocer un reintento como la misma operación en vez de una nueva. Funciona como un número de orden en un formulario en papel: si envías el mismo formulario dos veces por error, el funcionario receptor ve el número de orden y solo lo procesa una vez. Sin una clave de idempotencia, un problema de red en una solicitud de transferencia podría crear silenciosamente dos transferencias.

Antes de empezar

Esta página asume que has leído Autenticación y que haces solicitudes POST, PUT o PATCH contra la API de Mono. La idempotencia no aplica a solicitudes GET — esas ya son seguras de reintentar por definición.

Cuándo enviarla

Envía una clave de idempotencia cuando un reintento de la misma solicitud no debe producir un segundo efecto secundario. En la práctica, esto es cada solicitud de escritura a Mono. Ejemplos:

• Crear una transferencia bancaria.
• Crear un enlace de recaudo.
• Crear una tarjeta.
• Disparar una dispersión.
• Enviar una transferencia saliente Bre-B.

También puedes enviar una en solicitudes que teóricamente son seguras de reintentar (como updates que convergen al mismo estado). Nunca está mal incluir el header.

Cómo enviarla

Agrega el header X-Idempotency-Key a tu solicitud. El valor es una cadena que tú generas, única por operación lógica, de hasta 255 caracteres.

curl https://api.cuentamono.com/v1/bank_transfers \
  -H "Authorization: Bearer $MONO_API_KEY" \
  -H "X-Idempotency-Key: payroll-2026-05-06-emp-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500000,
    "currency": "COP",
    "routing": "turbo",
    "destination": { ... }
  }'

Cómo elegir una buena clave

Una buena clave de idempotencia es determinística para una operación lógica dada y opaca para humanos. Formatos recomendados:

• Un UUID v4 generado una vez por operación lógica y almacenado junto a la operación en tu base de datos. Persiste la clave antes del primer intento para que los reintentos la reusen.
• Un compuesto de identificadores que tu sistema ya controla — por ejemplo transfer:${order_id} para una transferencia por orden. Evita timestamps a menos que los controles con precisión; los relojes derivan entre reintentos.

Qué evitar:

• Reusar la misma clave para operaciones distintas. Mono tratará la segunda como un duplicado y responderá con la respuesta cacheada de la primera, lo cual casi seguramente no es lo que quieres.
• Generar una clave nueva en cada reintento. Eso anula el propósito completo — los reintentos se vuelven operaciones nuevas.
• Incluir secretos o PII en la clave. Las claves aparecen en logs y dashboards.

Qué hace Mono con ella

Cuando Mono recibe una solicitud con una clave de idempotencia, busca la clave en su almacén de corto plazo:

1. Vista por primera vez — Mono ejecuta la solicitud, almacena la respuesta y la devuelve.
2. Ya vista, mismo payload — Mono devuelve la respuesta almacenada sin ejecutar la solicitud de nuevo. Tu reintento es seguro.
3. Ya vista, payload distinto — Mono rechaza la solicitud con 409 Conflict. Esto te protege de un bug donde dos operaciones no relacionadas comparten una clave por accidente.

Las respuestas cacheadas se retienen por 24 horas desde la primera solicitud. Después de eso la clave se olvida y una solicitud nueva con la misma clave inicia una operación nueva.

Cuándo tienen sentido los reintentos

Reintenta solo en fallas transitorias — timeouts de red, 502, 503, 504. No reintentes en 400, 401, 403, 404 o 422; esos indican que la solicitud está mal, y reintentar no cambiará la respuesta.

Usa backoff exponencial con jitter, y limita el presupuesto de reintentos. Un patrón común: 3 reintentos, empezando en 1s, doblando cada vez, con 0–500ms de jitter.

Errores comunes

Siguientes pasos

• Errores y reintentos — cómo Mono señala fallas reintentables vs. terminales y la política estándar de backoff.
• Autenticación — manejo y rotación de credenciales.
• Paginación y ordenamiento — convenciones de cursor para endpoints de lectura.