1. Prompt y escenario
Una API de pedidos acepta solicitudes JSON. Un cliente puede enviar datos sintácticamente válidos con relaciones de campos no válidas, actualizar un pedido a partir de una versión antigua o intentar crear un nombre de usuario que ya existe. Defina el límite entre 409 y 422 para que los clientes sepan si deben editar la solicitud, volver a leer el recurso o dejar de reintentar.
2. Qué está evaluando el entrevistador
- Si separa la semántica de una solicitud no procesable de un conflicto con el estado actual del recurso.
- Si comprende que repetir una solicitud 422 sin cambios normalmente produce el mismo resultado.
- Si conecta el control de concurrencia, los reintentos idempotentes y un contrato de errores.
- Si puede posicionar las respuestas 400 y 412 adyacentes y mantener la política consistente.
3. Preguntas clarificadoras para hacer
- ¿Utiliza la API ETags, números de versión u otro mecanismo de concurrencia optimista?
- ¿Se modela "el nombre ya existe" como una regla de campo o como el estado actual de una colección?
- ¿Puede el cliente volver a leer el recurso y mostrar un diff al usuario?
- ¿El equipo ya estandariza códigos de error, rutas de campos (field paths) y el comportamiento de los reintentos?
4. Estructura de respuesta de 30 segundos
Clasifique la causa primero. Devuelva 422 cuando el servidor entienda el tipo de medio y la sintaxis pero no pueda procesar la semántica de la solicitud. Devuelva 409 cuando la solicitud comprensible entre en conflicto con el estado actual del recurso de destino. Use 400 para una solicitud que no se puede parsear y 412 para una precondición fallida de solicitud condicional cuando ese sea el contrato preciso. Concluya con códigos legibles por máquina, guía de corrección e información de versión.
5. Solución paso a paso
Paso uno: Definir el límite de 422
422 significa que el tipo de contenido y la sintaxis se entienden, pero las instrucciones contenidas no se pueden procesar. Los ejemplos incluyen una fecha de fin anterior a la fecha de inicio, un valor de enum no permitido o una combinación de campos no válida. El fallo suele ser independiente de quién modificó el recurso por última vez, por lo que el cliente debe modificar el payload antes de enviarlo nuevamente.
Paso dos: Definir el límite de 409
409 significa que la solicitud entra en conflicto con el estado actual del recurso de destino. Casos típicos son una versión obsoleta, cancelar un pedido que ya ha sido enviado o crear un recurso que colisiona con un recurso único existente. Incluya la versión actual, el tipo de conflicto y un siguiente paso práctico cuando sea seguro hacerlo.
Paso tres: Posicionar los códigos adyacentes
Use 400 para JSON mal formado o sintaxis faltante necesaria para parsear la solicitud. Una solicitud con If-Match que no cumple con su condición establecida puede usar 412; esto es más preciso que catalogar cada fallo condicional como un 409. Documente la política elegida para que los endpoints no inventen significados incompatibles.
Paso cuatro: Diseñar los reintentos y el cuerpo del error
No reintente automáticamente un payload 422 sin cambios porque se espera que falle de nuevo. Un 409 puede ser corregible: vuelva a leer, fusione y reintente cuando el tipo de conflicto lo permita, pero nunca cree un bucle a ciegas. Devuelva un code estable, la ruta del campo o el identificador del recurso, la versión actual y una guía de corrección; mantenga las credenciales y otros secretos fuera de la respuesta y de los registros.
6. Respuesta modelo
Clasifico el fallo como un problema semántico del payload o como una condición de carrera con el estado del recurso. Los rangos de fechas invertidos, enums no válidos y combinaciones de campos imposibles son 422. Un servidor que comprende la solicitud pero observa un pedido ya enviado, una versión obsoleta o un recurso único existente puede devolver 409. Un JSON mal formado es 400, y una condición If-Match no cumplida puede ser 412.
>
Para 422, devuelvo un código de negocio estable y la ruta del campo para que el cliente edite los datos. Para 409, devuelvo el tipo de conflicto y la versión o estado del servidor para que el cliente pueda volver a leer y elegir entre fusionar, abandonar o reintentar. Ninguno de los dos estados debería desencadenar reintentos incondicionales; una clave de idempotencia evita la ejecución duplicada, pero no elimina un conflicto de concurrencia. Documento una política única para todos los endpoints y monitoreo cómo se repara cada error.
7. Errores comunes
- Devolver 409 para cada fallo de validación de negocio, dando a entender que volver a leer el recurso lo solucionará.
- Devolver 422 para un conflicto de versión y ocultar la señal de que el estado cambió.
- Agregar reintentos automáticos ilimitados para cualquiera de los dos estados y crear una tormenta de solicitudes.
- Devolver solo un mensaje legible para humanos sin un código estable, ruta de campo o dirección de reparación.
- Elegir un único código para cada "duplicado" sin definir si se trata de una regla del payload o de un conflicto con el estado del recurso.
8. Preguntas de seguimiento y respuestas
Pregunta de seguimiento uno: ¿Un nombre de usuario duplicado debería ser 409 o 422?
Si la unicidad se modela como el estado actual de la colección, 409 comunica un conflicto de estado. Si el equipo la modela como validación semántica del campo, 422 puede ser consistente. Los contratos estables y el comportamiento predecible del cliente importan más que una etiqueta universal.
Pregunta de seguimiento dos: ¿Todo 409 es reintentable?
No. Un conflicto de versiones se puede reintentar después de fusionar, mientras que la cancelación de un pedido ya enviado debería detenerse y mostrar el estado actual. La respuesta debe comunicar si el conflicto es corregible.
Pregunta de seguimiento tres: ¿Puede 422 representar un fallo de permisos?
No debería reemplazar la semántica de autenticación y autorización. La falta de autenticación es generalmente 401, y un cliente autenticado sin permisos es generalmente 403. Reserve 422 para contenidos cuya semántica no se pueda procesar.