2627: Violation of PRIMARY KEY / UNIQUE KEY constraint. Cannot insert duplicate key in object

O que significa?

Você tentou inserir ou atualizar um valor que já existe em coluna(s) protegida(s) por uma constraint PRIMARY KEY ou UNIQUE. Chaves duplicadas não são aceitas.

Por que acontece?

Inserção do mesmo valor único uma segunda vez, um UPDATE colidindo com um valor existente, ausência de verificação de unicidade, ou duas requisições concorrentes produzindo a mesma linha.

Como resolver

Verifique se a linha existe antes de inserir, ou use MERGE / IF NOT EXISTS. Para inserts idempotentes, aplique o padrão "INSERT ... WHERE NOT EXISTS". Capture o erro e retorne uma mensagem significativa. Se você realmente precisa de dados duplicados, revise a constraint. Use IDENTITY ou SEQUENCE para evitar colisões ao gerar chaves.