HTTP 409 Conflict: qué significa y cómo solucionarlo

Qué significa este error y cómo reconocerlo

• Un navegador, cliente de API, herramienta de monitorización o integración recibe una respuesta HTTP 409 Conflict.
• La creación o actualización de un recurso falla mientras otras páginas o rutas de la API siguen funcionando.
• El error puede producirse solo con un método HTTP, como POST, PUT o PATCH.
• Repetir la misma solicitud produce el mismo conflicto, mientras que una solicitud para otro recurso tiene éxito.
• El cuerpo de la respuesta puede identificar un recurso existente, una versión obsoleta, un valor duplicado, una transición de estado o una regla de la aplicación.
• El DNS puede seguir resolviendo y TLS puede seguir funcionando porque la solicitud llegó a un endpoint que habla HTTP; son comprobaciones independientes.

Causas principales, ordenadas por probabilidad

1. Ya existe un recurso o se ha duplicado un valor único. Una operación de creación puede entrar en conflicto con un registro, nombre de usuario, identificador, nombre de archivo u otro valor con una restricción de unicidad que ya existe.
2. Una actualización simultánea u obsoleta. El recurso puede haber cambiado desde la última lectura del cliente, por lo que la versión enviada ya no coincide con el estado actual.
3. Una transición de estado no válida. La aplicación puede rechazar una operación que no está permitida en el estado actual del recurso, como modificar un elemento completado, archivado o bloqueado.
4. Reglas de la aplicación o del servidor web. La lógica de las rutas, la validación, las políticas de solicitudes o el tratamiento personalizado de errores pueden devolver deliberadamente 409 para un conflicto conocido.
5. Comportamiento del proxy, la CDN o el WAF. Un intermediario puede generar o transformar la respuesta debido al enrutamiento, la caché, la inspección de solicitudes o la configuración del upstream.
6. Reglas de autenticación o autorización específicas del entorno. Algunas aplicaciones usan 409 para un conflicto relacionado con el estado de una cuenta o un recurso, aunque los fallos de autenticación suelen utilizar otros códigos de estado. Confirma el comportamiento a partir de la respuesta y los registros en lugar de asumir el origen del código de estado.

Cómo solucionarlo

Primero, confirma la solicitud

1. Registra la URL exacta, el método HTTP, el cuerpo de la solicitud, el usuario autenticado o el contexto del cliente, la hora y el código de estado final.
2. Comprueba las cabeceras y el cuerpo de la respuesta en busca de un identificador del conflicto, la ubicación del recurso, información de versión, el estado de la caché, un indicador del proxy o un mensaje de error de la aplicación.
3. Confirma si hubo redirecciones y si el 409 provino del endpoint final o de un intermediario.
4. Evita cambiar la configuración hasta saber si la respuesta es intencionada para esa ruta y método.

Si eres visitante o consumidor de una API

1. Verifica la URL, la cuenta o el recurso seleccionados y los datos enviados.
2. Si la operación crea un recurso, comprueba si ya existe antes de volver a enviarla.
3. Si la operación actualiza un recurso, vuelve a cargar u obtén la versión actual y reintenta solo mediante el flujo de actualización compatible con la aplicación.
4. Inicia sesión mediante el flujo normal de la cuenta si el recurso requiere autenticación; no envíes contraseñas ni tokens a una página que no sea de confianza.
5. Evita reintentos repetidos cuando la respuesta indique un duplicado, un estado bloqueado o un límite del servidor.
6. Si el conflicto persiste, envía al propietario del sitio o al proveedor de la API el endpoint, el método, la marca de tiempo, el cuerpo de la respuesta y un identificador de solicitud anonimizado. Elimina contraseñas, cookies, claves de API y datos personales.

Si mantienes el sitio web o la API

1. Reproduce el problema con el mismo método, URL, datos de la solicitud y contexto de cuenta o cliente. Usa un entorno de pruebas o staging cuando la operación modifique datos.
2. Determina qué componente generó la respuesta: la aplicación, el servidor web, el reverse proxy, la CDN o el WAF. Compara las cabeceras de respuesta, las firmas del servidor y los identificadores de solicitud cuando estén disponibles.
3. Busca los registros correspondientes en ese componente y relaciona la marca de tiempo, la ruta, el método, el identificador del usuario o cliente y la respuesta del upstream.
4. En las operaciones de creación, comprueba las restricciones de duplicados o de campos únicos. En las actualizaciones, comprueba el bloqueo optimista, la versión, ETag u otros datos de concurrencia utilizados por la aplicación.
5. Revisa el estado actual del recurso y las transiciones de estado permitidas por la aplicación. No evites un conflicto simplemente eliminando o sobrescribiendo datos, salvo que esa acción esté autorizada y se comprenda bien.
6. Compara las implementaciones recientes y los cambios en el enrutamiento, la validación, la autenticación, la caché, el proxy y las reglas del WAF.
7. Aplica la corrección documentada más específica, vuelve a probar la misma solicitud y realiza una solicitud normal para las rutas relacionadas. Confirma que el cuerpo, las cabeceras y el código de estado de la respuesta coinciden ahora con el comportamiento previsto.
8. Si el 409 es intencionado, haz que la respuesta sea útil explicando el conflicto y, cuando corresponda, indicando cómo el cliente puede actualizar el estado, elegir otro valor o resolverlo.

Prevención y cómo verificar la solución

• Documenta qué operaciones pueden devolver 409 intencionadamente y qué deben hacer los clientes a continuación.
• Usa mensajes claros sobre duplicados, versiones obsoletas y estados no válidos en las respuestas de la API.
• Prueba los flujos de creación, actualización y actualización simultánea después de las publicaciones de la aplicación.
• Mantén bajo control de versiones la configuración del enrutamiento, el proxy, la autenticación, la caché y el WAF.
• Supervisa los códigos de estado por ruta y método HTTP en lugar de tratar todas las respuestas 409 como un único problema.
• Conserva los registros de la aplicación y la infraestructura durante el tiempo suficiente para relacionar los conflictos con las implementaciones y los cambios de configuración.
• Utiliza una estrategia de concurrencia documentada, como el mecanismo de versiones o de actualización condicional compatible con la aplicación.

Preguntas frecuentes