Erro 2627 no SQL Server: violação de chave primária/única

Mensagem completa: "Violation of PRIMARY KEY constraint 'PK_Tabela'. Cannot insert duplicate key in object 'dbo.Tabela'. The duplicate key value is (123)." — Msg 2627, Level 14. A mesma mensagem aparece para constraint UNIQUE, só troca "PRIMARY KEY" por "UNIQUE KEY" no texto.

Isso não é um bug do banco

A constraint fez exatamente o que deveria: impediu um dado duplicado de entrar. O erro é um sintoma — a causa está em quem gerou o valor duplicado, não no banco.

Causas mais comuns

• Race condition na aplicação: duas requisições concorrentes verificam "não existe" e depois as duas tentam inserir, sem lock ou constraint impedindo entre a verificação e a inserção.
• Coluna IDENTITY reseedada manualmente (DBCC CHECKIDENT) para um valor que já foi usado antes.
• Reprocessamento de ETL/importação sem checagem de idempotência — o mesmo arquivo/lote rodou duas vezes.
• Réplica ou ambiente restaurado gerando os mesmos IDs de novo em paralelo com o ambiente original (comum após restore de disaster recovery mal isolado).

Como investigar

O valor duplicado já vem na própria mensagem de erro ("the duplicate key value is...") — comece consultando esse valor específico na tabela pra ver se já existe uma linha idêntica ou se são duas gerações concorrentes tentando o mesmo ID. Se for race condition, a correção é usar MERGE/UPSERT com tratamento do erro 2627, ou uma constraint + retry, em vez de checar existência antes de inserir.