En esta página
Una clave para la misma intención
Envíe Idempotency-Key al crear una transacción. El header es opcional en el contrato, pero se recomienda para tolerar una conexión perdida después de que el servidor recibe la solicitud. Genere y guarde la clave antes del primer POST; reutilícela solo para la misma creación y el mismo payload.
Idempotency-Key: onboarding-demo-0001Perder la respuesta no significa perder la creación
Si su servidor envía una solicitud y recibe un timeout, la transacción puede existir. Repetir con otra clave puede crear un segundo recorrido. Repetir el mismo POST con la misma clave y payload permite recuperar la creación idempotente; la respuesta documentada sigue siendo 201.
Utilice external_id para correlación de negocio, sin considerarlo un sustituto automático del header. Conserve la relación entre clave, intento y transacción en su sistema.
Trate el conflicto explícitamente
La misma clave con un payload diferente devuelve 409 con código idempotency_conflict. No evite ese resultado cambiando la clave silenciosamente. Investigue si el cliente modificó los datos o si su aplicación reconstruyó la solicitud de forma inconsistente.
Una intención nueva recibe una clave nueva. Un reintento técnico conserva la intención anterior. No suponga un plazo de retención de claves no documentado para su contrato.
La idempotencia de creación no sustituye la deduplicación de webhooks. Para eventos, utilice event_id y haga también idempotentes los efectos de negocio.