4xx · Errores del cliente
Error 409 Conflict: qué significa y cómo solucionarlo
El error 409 Conflict indica que la petición no se puede completar porque choca con el estado actual del recurso: crear un usuario con un email que ya existe, editar un documento que otra persona ha modificado entretanto o subir una versión más antigua que la guardada.
Qué significa el código 409
Es la respuesta adecuada para conflictos de negocio que el cliente puede resolver: elegir otro nombre, recargar el documento y volver a aplicar los cambios, etc. La API debería explicar en el cuerpo cuál es el conflicto.
Causas habituales del error 409
- Valor único duplicado (email, nombre de usuario, slug).
- Edición concurrente con control de versiones (ETag, campo version).
- En Git sobre HTTP, o en S3, operaciones sobre recursos en un estado incompatible.
Cómo solucionar el error 409
- Muestra al usuario qué ha fallado ("este email ya está registrado").
- Para ediciones concurrentes, usa If-Match con ETag y responde 412 si ha cambiado.
Configuración y comandos
FastAPI
python
from fastapi import HTTPException
if await db.usuarios.find_one({"email": datos.email}):
raise HTTPException(status_code=409, detail="Ya existe una cuenta con ese email")Ejemplo de respuesta
http
HTTP/1.1 409 Conflict
Content-Type: application/json
{"detail": "Ya existe una cuenta con ese email"}Preguntas frecuentes
¿409 o 400 para un email duplicado?
409 es más preciso: la petición es válida, pero entra en conflicto con un dato que ya existe.