# Idempotencia y reintentos · Documentación de Pagos Express

> Contrato de Idempotency-Key en Pagos Express: replay de 24 horas, huella del cuerpo, 409 request_in_flight, 422 idempotency_key_reuse y cómo reintentar con seguridad.

HTML: https://pagos.express/docs/idempotencia
Texto para modelos: https://pagos.express/docs/idempotencia.llms.txt
Índice de la documentación: https://pagos.express/docs

## Contrato
- `POST /v1/payment_links`: requiere Idempotency-Key. La respuesta exitosa se conserva 24 horas y se devuelve byte a byte.
- `POST /v1/payment_links/{id}/disable`: clave opcional. Repetir deja el enlace desactivado.
- `POST /v1/payment_links/{id}/email`: requiere clave. Evita enviar el mismo correo dos veces.
- `POST /v1/payments/{id}/sync`: idempotente por naturaleza.

La clave: 1–255 caracteres ASCII visibles, sin espacios. Un UUID nuevo por intención; el mismo en cada reintento.

## Reglas
- Las claves se limitan a cuenta y modo, y se comparten entre REST, dashboard y MCP.
- La huella incluye la operación y el cuerpo validado y normalizado. El orden de propiedades no importa; el de los conceptos sí.
- Un replay responde estado y cuerpo originales con `Idempotency-Replayed: true`.
- Misma clave con otro cuerpo u operación: `422 idempotency_key_reuse`, sin ejecutar nada.
- Trabajo concurrente con la misma clave: `409 request_in_flight`. Espera y reintenta con la misma clave.
- Solo las mutaciones confirmadas en la base de datos se guardan; un error de validación no deja nada cacheado.
- Tras 24 horas la clave puede crear un recurso nuevo.

## Patrón
Genera `key = randomUUID()` y guárdala junto a tu pedido. Reintenta con la misma clave y el mismo cuerpo; ante 409 espera con backoff; ante otro 4xx corrige antes de reintentar.