10 — Reintentos seguros con `Idempotency-Key`

Una solicitud puede fallar por un timeout o un corte de red después de que Yallegó la ejecutó. Si la repites a ciegas, puedes confirmar dos veces desde dos sistemas, registrar dos veces el mismo webhook o no saber si el 409 que recibes es tuyo. Con Idempotency-Key, repetir es seguro: la segunda vez recibes exactamente la misma respuesta que la primera, sin que se vuelva a ejecutar.

Dónde se acepta

Ruta	Qué evita al repetir
`POST /v1/transactions/{id}/confirm`	Confundir tu confirmación con la de otro sistema
`POST /v1/transactions/{id}/dispute`	Lo mismo, al reportar un cobro
`POST /v1/transactions/export`	Generar otra exportación con datos que cambiaron
`POST /v1/webhooks`	Un endpoint duplicado que consume cupo del plan
`POST /v1/webhooks/{id}/test`	Un segundo evento de prueba
`POST /v1/webhooks/{id}/rotate-secret`	Rotar dos veces y perder el secreto que guardaste
`POST /v1/webhooks/{id}/deliveries/{deliveryId}/retry`	Encolar dos veces el mismo reintento

La cabecera es opcional. Sin ella, cada solicitud se ejecuta como siempre.

Cómo usarla

Genera una clave nueva por operación (no por intento) y reutilízala solo para reintentar esa misma operación:

curl -X POST https://api.yallego.app/v1/transactions/{id}/confirm \
  -H "Authorization: Bearer yk_live_..." \
  -H "Idempotency-Key: 3f6a8c2e-1b5d-4f9a-8c6e-9f8c2a1e4b7d" \
  -H "Content-Type: application/json" \
  -d '{"note": "ref:pago-4821"}'

Formato: de 1 a 255 caracteres ASCII visibles, sin espacios. Te recomendamos un UUID v4; también sirve un identificador propio estable, p. ej. confirmar:pago-4821. Una clave inválida responde 400 VALIDATION_ERROR con details.header = "Idempotency-Key".
Alcance: cada clave de API tiene su propio espacio de claves, separado por método y ruta. El mismo valor usado desde otra clave de API, otro comercio u otra ruta es una clave distinta.
Vigencia: 24 horas desde la primera solicitud. Pasado ese plazo, la misma clave se trata como nueva.

Qué responde

Situación	Respuesta
Primera vez	Se ejecuta y se guarda la respuesta
Repites con la misma ruta, query y cuerpo	El mismo estado y cuerpo, con la cabecera `Idempotent-Replayed: true`
Repites mientras la primera sigue en curso	`409 IDEMPOTENCY_KEY_IN_USE` con `Retry-After: 1`: espera y vuelve a intentar
Usas la clave con otro cuerpo, otra transacción u otros filtros	`422 IDEMPOTENCY_KEY_REUSED`: es un error de tu integración, usa una clave nueva

Se guardan los éxitos (2xx) y los rechazos que dependen del estado del recurso (404, 409, 422): repetir te devuelve el mismo rechazo. Los errores de validación (400), de credencial o alcance (401, 403), de límite de tasa (429) y del servidor (5xx) no se guardan: corrige y reintenta con la misma clave.

// 422 — la clave ya se usó con otra solicitud
{
  "error": {
    "code": "IDEMPOTENCY_KEY_REUSED",
    "message": "Esta clave de idempotencia ya se usó con otra solicitud. Usa una clave nueva para cada operación.",
    "details": { "idempotency_key": "3f6a8c2e-1b5d-4f9a-8c6e-9f8c2a1e4b7d" },
    "request_id": "b7f3a2e1-..."
  }
}

¿El cobro ya era mío? El `409` de `confirm` y `dispute`

Si la transacción ya no admite el cambio, el 409 CONFLICT dice cómo quedó. Comparando note con la que enviaste sabes si el cambio fue tuyo sin otra consulta:

{
  "error": {
    "code": "CONFLICT",
    "message": "Solo una transacción capturada puede confirmarse.",
    "details": { "status": "CONFIRMED", "note": "ref:pago-4821" },
    "request_id": "b7f3a2e1-..."
  }
}

Con Idempotency-Key normalmente no llegas a ese caso: si tu primera confirmación se ejecutó y se perdió la respuesta, la repetición te devuelve el 200 original.

Casos límite

Respuestas con datos sensibles. La respuesta guardada de POST /v1/webhooks incluye el secret: la repetición lo devuelve igual, así que trátala con el mismo cuidado. Yallegó la guarda cifrada.
Caída del servidor a mitad de la ejecución. Si Yallegó cae mientras ejecuta tu solicitud, la clave queda reservada unos 60 segundos y luego una repetición idéntica se ejecuta otra vez. En confirm y dispute recibirás el 409 con el estado actual, que te dice si el cambio quedó hecho.
Panel. Las sesiones del panel también pueden enviar la cabecera; su alcance es el usuario, no una clave de API.