HTTP 409 Conflict: o que significa e como corrigir

O que este erro significa e como reconhecê-lo

• Um navegador, cliente de API, ferramenta de monitoramento ou integração recebe uma resposta HTTP 409 Conflict.
• A criação ou atualização de um recurso falha, enquanto outras páginas ou rotas da API continuam funcionando.
• O erro pode ocorrer apenas com um método HTTP, como POST, PUT ou PATCH.
• Repetir a mesma solicitação produz o mesmo conflito, enquanto uma solicitação para outro recurso é bem-sucedida.
• O corpo da resposta pode identificar um recurso existente, uma versão desatualizada, um valor duplicado, uma transição de estado ou uma regra da aplicação.
• O DNS ainda pode resolver e o TLS ainda pode ser concluído porque a solicitação chegou a um endpoint que fala HTTP; essas são verificações separadas.

Causas principais, por probabilidade

1. Um recurso já existe ou um valor exclusivo está duplicado. Uma operação de criação pode entrar em conflito com um registro, nome de usuário, identificador, nome de arquivo ou outro valor sujeito a uma restrição de exclusividade.
2. Uma atualização simultânea ou desatualizada. O recurso pode ter sido alterado desde a última leitura feita pelo cliente, portanto a versão enviada já não corresponde ao estado atual.
3. Uma transição de estado inválida. A aplicação pode rejeitar uma operação que não é permitida no estado atual do recurso, como modificar um item concluído, arquivado ou bloqueado.
4. Regras da aplicação ou do servidor web. A lógica da rota, a validação, as políticas de solicitação ou o tratamento de erros personalizado podem retornar deliberadamente 409 para um conflito conhecido.
5. Comportamento de proxy, CDN ou WAF. Um intermediário pode gerar ou transformar a resposta por causa de roteamento, cache, inspeção da solicitação ou configuração do upstream.
6. Regras de autenticação ou autorização específicas do ambiente. Algumas aplicações usam 409 para um conflito envolvendo o estado de uma conta ou recurso, embora falhas de autenticação geralmente usem outros códigos de status. Confirme o comportamento na resposta e nos logs, em vez de presumir a origem do código de status.

Como corrigir

Primeiro, confirme a solicitação

1. Registre a URL exata, o método HTTP, o corpo da solicitação, o usuário autenticado ou contexto do cliente, o horário e o código de status final.
2. Verifique os cabeçalhos e o corpo da resposta em busca de um identificador de conflito, localização do recurso, informações de versão, status do cache, indicador de proxy ou mensagem de erro da aplicação.
3. Confirme se ocorreram redirecionamentos e se o 409 veio do endpoint final ou de um intermediário.
4. Evite alterar a configuração até saber se a resposta é intencional para aquela rota e método.

Se você é visitante ou consumidor de API

1. Verifique a URL, a conta ou o recurso selecionado e os dados enviados.
2. Se a operação criar um recurso, verifique se ele já existe antes de enviá-la novamente.
3. Se a operação atualizar um recurso, recarregue ou obtenha a versão atual e repita a tentativa somente usando o fluxo de atualização compatível com a aplicação.
4. Faça login pelo fluxo normal da conta se o recurso exigir autenticação; não envie senhas ou tokens para uma página não confiável.
5. Evite novas tentativas repetidas quando a resposta indicar uma duplicidade, um estado bloqueado ou um limite do servidor.
6. Se o conflito persistir, envie ao proprietário do site ou provedor da API o endpoint, o método, o horário, o corpo da resposta e um identificador de solicitação sanitizado. Remova senhas, cookies, chaves de API e dados pessoais.

Se você mantém o site ou a API

1. Reproduza o problema com o mesmo método, URL, dados da solicitação e contexto da conta ou do cliente. Use um ambiente de teste ou staging quando a operação alterar dados.
2. Determine qual componente gerou a resposta: aplicação, servidor web, reverse proxy, CDN ou WAF. Compare os cabeçalhos da resposta, as assinaturas do servidor e os identificadores de solicitação, quando disponíveis.
3. Pesquise os logs correspondentes nesse componente e correlacione o horário, a rota, o método, o usuário ou identificador do cliente e a resposta do upstream.
4. Para operações de criação, verifique as restrições de duplicidade ou de campos exclusivos. Para atualizações, verifique os dados de bloqueio otimista, versão, ETag ou outros dados de concorrência usados pela aplicação.
5. Analise o estado atual do recurso e as transições de estado permitidas pela aplicação. Não contorne um conflito simplesmente excluindo ou substituindo dados, a menos que essa ação seja autorizada e compreendida.
6. Compare implantações recentes e alterações no roteamento, na validação, na autenticação, no cache, no proxy e nas regras do WAF.
7. Aplique a correção documentada mais específica, depois teste novamente a mesma solicitação e uma solicitação normal para rotas relacionadas. Confirme que o corpo, os cabeçalhos e o código de status da resposta agora correspondem ao comportamento esperado.
8. Se o 409 for intencional, torne a resposta acionável explicando o conflito e, quando apropriado, indicando como o cliente pode atualizar os dados, escolher um valor diferente ou resolver o estado.

Prevenção e como verificar a correção

• Documente quais operações podem retornar 409 intencionalmente e o que os clientes devem fazer em seguida.
• Use mensagens claras sobre duplicidade, versão desatualizada e estado inválido nas respostas da API.
• Teste os fluxos de criação, atualização e atualização simultânea após as versões da aplicação.
• Mantenha a configuração de roteamento, proxy, autenticação, cache e WAF sob controle de versão.
• Monitore códigos de status por rota e método HTTP, em vez de tratar todas as respostas 409 como um único problema.
• Retenha os logs da aplicação e da infraestrutura por tempo suficiente para correlacionar conflitos com implantações e alterações de configuração.
• Use uma estratégia de concorrência documentada, como o mecanismo de versão ou de atualização condicional compatível com a aplicação.

Perguntas frequentes