A requisição conflita com o estado atual.
Quando usar
Valores únicos duplicados ou uma edição baseada em uma versão desatualizada.
Causas comuns e soluções
O 409 significa que a requisição é válida, mas conflita com o estado atual. Casos típicos: inserir um nome de usuário ou e-mail duplicado que viola uma restrição de unicidade, criar algo que já existe ou salvar um registro que outra pessoa alterou desde que você o leu, detectado por uma coluna de versão. Mapeie a violação de unicidade do banco de dados (Postgres 23505, MySQL 1062) para 409 em vez de deixá-la aparecer como 500.
O corpo deve dizer o que conflitou e, idealmente, incluir a versão atual, para que o cliente possa mesclar ou perguntar ao usuário. Tentar de novo sem mudanças falha outra vez, a menos que o conflito tenha sido transitório, como um lock mantido por outra transação. O Kubernetes retorna 409 quando uma atualização traz um resourceVersion desatualizado; a solução é o loop de sempre: ler de novo, reaplicar a alteração e reenviar.
Erro do cliente (4xx)
Os códigos 4xx são erros do cliente: a própria requisição está errada, não está autorizada ou aponta para algo que não existe. Repetir a mesma requisição não vai adiantar.
Como fica
HTTP/1.1 409 ConflictComo enviar
| Node.js / Express | res.status(409).end() |
|---|---|
| Python / Flask | return '', 409 |
| nginx | return 409; |
Como verificar
curl -s -o /dev/null -w "%{http_code}\n" https://example.com/