HTTP 409 Conflict — Causas e soluções

O que significa HTTP 409

HTTP 409 Conflict significa que o servidor entendeu a requisição, mas não pode aplicá-la porque ela contradiz o estado atual do recurso de destino. O exemplo clássico é uma colisão de edição: dois clientes carregaram o mesmo documento, ambos salvam, e o segundo salvamento sobrescreveria silenciosamente o primeiro.

Diferente do 400, a requisição em si está bem formada — reenviá-la sem alterações pode até ter sucesso mais tarde. O corpo da resposta deve explicar o que está em conflito para que o cliente (ou usuário) possa resolvê-lo e tentar novamente.

Causas comuns dos erros 409

Uma colisão de edição: o recurso foi modificado por outra pessoa desde a última vez que o cliente o buscou (frequentemente evidenciado via ETag / If-Match).
Criar um recurso que já existe — nome de usuário, e-mail, slug ou nome de arquivo duplicado.
Uma incompatibilidade de versão no optimistic locking: o número de versão enviado está desatualizado.
Excluir ou mover um recurso que tem dependentes que o servidor se recusa a deixar órfãos.
Etapas de um fluxo de trabalho concorrente aplicadas fora de ordem (por exemplo, aprovar um pedido já cancelado).

Como corrigir como desenvolvedor

Leia o corpo da resposta — uma boa API indica o campo em conflito ou a versão atual esperada.
Busque o recurso novamente, reaplique sua alteração sobre o estado atualizado e reenvie a requisição.
Use requisições condicionais (If-Match com ETags) para que os conflitos sejam detectados de forma confiável em vez de sobrescrever dados.
Para conflitos de criação duplicada, decida a idempotência com antecedência: retorne o recurso existente, ou 409 com uma referência a ele.

Exemplo de resposta

HTTP/1.1 409 Conflict
Content-Type: application/json

{"error":"conflict","message":"document was modified by another user","current_version":42}

Perguntas frequentes

Qual é a diferença entre 409 e 400?

400 significa que a própria requisição está malformada ou inválida. 409 significa que a requisição está correta, mas entra em conflito com o estado atual do recurso — tentar novamente após resolver o conflito pode ter sucesso.

Quando uma API deve retornar 409 em vez de 422?

Use 422 para falhas de validação dentro do payload e 409 para colisões com o estado existente no servidor, como duplicatas ou versões desatualizadas.

Como os ETags ajudam a evitar erros 409?

O cliente envia If-Match com o ETag visto pela última vez; o servidor aplica a alteração somente se o recurso não tiver mudado, caso contrário retorna 409 (ou 412) em vez de sobrescrever.