¿Cuándo debe utilizarse HTTP 424 Failed Dependency y cómo diseñar un contrato de API seguro ante reintentos?

Escenario

Una API por lotes valida un pedido, reserva inventario y crea el pedido. Si la reserva de inventario falla, la creación del pedido nunca se ejecuta. El entrevistador le pide que diseñe la respuesta de error y justifique si HTTP 424 es apropiado.

Qué evalúa esto

Distinguir la semántica estandarizada de HTTP de las convenciones específicas del equipo.
Representar la completitud parcial, el trabajo omitido y los resultados desconocidos en un grafo de dependencias.
Diseñar la idempotencia, las condiciones de reintento y los detalles de error como un único contrato.

Respuesta modelo

El límite de 424

424 (Failed Dependency) está definido por la RFC 4918 de WebDAV: el método no se pudo completar porque otra operación falló. No es un alias genérico para cada error de servicio descendente (downstream). Una API que no sea WebDAV puede adoptar el código 424, pero su contrato público debe definir el significado, el comportamiento del cliente y las expectativas de compatibilidad.

Elección de un código de estado

412 Precondition Failed: no se cumplió una precondición de la solicitud, como If-Match.
409 Conflict: la solicitud entra en conflicto con el estado actual del recurso, como un cambio en la versión del inventario.
424 Failed Dependency: este paso depende explícitamente de un paso fallido en la misma solicitud o flujo de trabajo y, por lo tanto, no se ejecutó.
5xx: el servidor no pudo completar la solicitud debido a un fallo en el servicio, no porque la relación entre solicitudes explique el paso bloqueado.

No mapee mecánicamente un error 500 de una dependencia a 424. Primero decida si un paso en este flujo de trabajo fue bloqueado y si el cliente puede tomar una acción diferente a partir de ese hecho.

Cuerpo de respuesta y máquina de estados

Utilice Problem Details de RFC 9457 con type, title, status y detail estables, además de extensiones como blockedBy, operationId, retryable y completedSteps. Las extensiones de negocio forman parte del contrato y requieren versionado.

json

{
  "type": "https://api.example.com/problems/failed-dependency",
  "title": "Order creation was blocked",
  "status": 424,
  "detail": "Inventory reservation failed",
  "blockedBy": "reserve-inventory",
  "operationId": "op_123",
  "retryable": true,
  "completedSteps": ["validate-order"]
}

Reintentos y resultados desconocidos

Reintente automáticamente solo cuando retryable=true y se utilice la misma clave de idempotencia. Si la conexión se interrumpe después de que se confirmó la reserva de inventario, el cliente no puede catalogar el tiempo de espera como 424 porque el resultado del servidor es desconocido; debe consultar mediante operationId. Un efecto secundario completado no se puede revertir simulando que una segunda solicitud es nueva; proporcione compensación cuando el negocio lo requiera.

Errores comunes

Tratar 424 como un estado universal para todos los errores de microservicios.
Devolver únicamente texto en prosa sin un tipo de error estable ni un ID de operación.
Reintentar cada 424 generando reservas o pedidos duplicados.
Ocultar una interrupción del servicio detrás de 424, impidiendo que el monitoreo distinga un bloqueo del flujo de trabajo de un fallo en la plataforma.

Preguntas de seguimiento

¿Puede una solicitud por lotes tener éxito parcial?

Sí, pero devuelva el estado por elemento, la información de idempotencia y los detalles de dependencia. El estado HTTP del lote describe el resultado agregado; no puede reemplazar los resultados individuales. Si el negocio requiere atomicidad, indique si se revierten todos los cambios o si no se confirma ninguno.

¿Cuándo es 409 mejor que 424?

Los conflictos de versión de recursos y de estado de inventario son problemas del recurso actual y generalmente corresponden a 409. Utilice 424 cuando el paso actual se omitió porque falló otro paso en el mismo flujo de trabajo.

¿Qué sucede si la dependencia devuelve 503?

Si el paso actual está bloqueado y el contrato lo trata como un fallo de dependencia del flujo de trabajo, 424 puede incluir la causa raíz en sus detalles. Si el servicio en su conjunto no está disponible, devuelva 503 y utilice señales a nivel de servicio como Retry-After. El monitoreo y las políticas del cliente deben distinguir ambos casos.

¿Cómo se prueba el contrato?

Cubra el éxito de la dependencia, rechazo, tiempo de espera (timeout), pérdida de conexión tras confirmación, claves de idempotencia duplicadas, completitud parcial y consultas de recuperación. Valide el estado, los campos de Problem Details, el estado terminal y la cantidad de efectos secundarios en lugar de limitarse solo al número HTTP.

Rúbrica de evaluación

Aprobado

Explica con precisión el origen WebDAV de 424, delimita las fronteras para 409, 412 y 5xx, y propone una clave de idempotencia junto con una consulta de resultado desconocido.

Sólido

Diseña extensiones de Problem Details, estados de completitud parcial, categorías de monitoreo y condiciones seguras para reintentos automáticos.

Excelente

Justifica cada elección utilizando la atomicidad del negocio, grafos de dependencias, compensación y contratos versionados, advirtiendo al mismo tiempo sobre el riesgo de compatibilidad al usar 424 fuera de WebDAV.

Estrategia de respuesta

Primero establezca el origen estándar del código de estado, luego delimite los estados de cada paso y las fronteras de los efectos secundarios; finalmente concrete la decisión con un contrato de error consultable y seguro ante reintentos.

Fuentes

Estándar de códigos de estado

RFC 4918: WebDAV (IETF)

Semántica HTTP

RFC 9110: HTTP Semantics (IETF)

Formato de errores

RFC 9457: Problem Details for HTTP APIs (IETF)