HTTP 409 Conflict

Qué significa HTTP 409

HTTP 409 Conflict significa que el servidor entendió la solicitud pero no puede aplicarla porque contradice el estado actual del recurso objetivo. El ejemplo clásico es una colisión de edición: dos clientes cargaron el mismo documento, ambos guardaron, y el segundo guardado sobrescribiría silenciosamente el primero.

A diferencia de 400, la solicitud en sí está bien formada — reenviarla sin cambios puede incluso tener éxito más tarde. El cuerpo de la respuesta debería explicar qué entra en conflicto para que el cliente (o el usuario) pueda resolverlo y reintentarlo.

Causas comunes de los errores 409

• Una colisión de edición: el recurso fue modificado por otra persona desde la última vez que el cliente lo obtuvo (a menudo visible mediante ETag / If-Match).
• Crear un recurso que ya existe — nombre de usuario, email, slug o nombre de archivo duplicado.
• Una discrepancia de versión en optimistic locking: el número de versión enviado está desactualizado.
• Eliminar o mover un recurso que tiene dependientes que el servidor se niega a dejar huérfanos.
• Pasos de un flujo concurrente aplicados fuera de orden (por ejemplo, aprobar un pedido ya cancelado).

Cómo solucionarlo como desarrollador

• Lee el cuerpo de la respuesta — una buena API indica el campo en conflicto o la versión actual esperada.
• Vuelve a obtener el recurso, reaplica tu cambio sobre el estado actualizado y reenvía la solicitud.
• Usa solicitudes condicionales (If-Match con ETags) para que los conflictos se detecten de forma fiable en lugar de sobrescribir datos.
• Para conflictos de creación duplicada, decide la idempotencia de antemano: devuelve el recurso existente, o 409 con un enlace a él.

Ejemplo de respuesta

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

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

Preguntas frecuentes