¿Cómo haces que un endpoint de escritura sea seguro de reintentar?

Dale al cliente una clave de idempotencia, guárdala junto al resultado de la primera escritura correcta y devuelve ese resultado guardado ante cualquier repetición. Impón la unicidad a nivel de base de datos para que los duplicados concurrentes choquen en vez de escribir dos veces. Acota las claves por cliente, cadúcalas tras una ventana razonable y usa la clave natural de negocio, como el id de pedido, como ancla de deduplicación siempre que exista.

El cliente genera una clave de idempotencia, normalmente un UUID, y la manda como cabecera. En el servidor mantengo una tabla indexada por id de cliente más esa clave con una restricción de unicidad, y escribo la clave y la respuesta en la misma transacción que la escritura de negocio. Una repetición entonces choca con la restricción de unicidad o encuentra la fila guardada y simplemente reproduce la respuesta original, así que los reintentos salen gratis. Importan dos detalles. Primero, la unicidad tiene que vivir en la base de datos, porque si haces un select y luego un insert, dos reintentos concurrentes pasarán ambos la comprobación. Segundo, hay que decidir qué hacer cuando la segunda petición llega mientras la primera sigue ejecutándose. Nosotros devolvíamos 409 con un Retry-After en lugar de bloquear, lo que mantenía sano el pool de conexiones. También guardo un hash del cuerpo de la petición para que reutilizar una clave con contenido distinto se rechace en vez de devolver la respuesta equivocada en silencio.