Prompt y contexto
Un API gateway requiere que los clientes utilicen HTTP/3, pero recibe una solicitud HTTP/1.1. Explique cuándo devolver 426, qué debe contener la respuesta, cómo se recupera un cliente y por qué no toda discrepancia de protocolo debe convertirse en un 426.
HTTP 426 significa que el servidor se rehúsa a procesar la solicitud utilizando el protocolo actual, pero podría hacerlo después de que el cliente se actualice. La RFC 9110 ofrece un ejemplo con Upgrade: HTTP/3.0. Se trata de una solicitud procesable de actualización de protocolo, no de un error genérico de parámetros, una falla de enlace TLS o una prueba de que el servidor no puede servir el recurso en absoluto.
Qué está evaluando el entrevistador
El entrevistador está evaluando la semántica precisa de 426, el límite entre el campo Upgrade y la negociación de TLS o versiones de HTTP, así como su manejo de cachés, proxies, reintentos idempotentes, telemetría y compatibilidad de clientes. También debe distinguir entre 400, 421 y 505.
Preguntas aclaratorias
Confirme si la actualización concierne a HTTP, la conexión TLS o una versión de la aplicación; si el cliente puede establecer el protocolo de destino; si el método es seguro de reintentar; si hay un proxy frente al gateway; y si la solicitud original debe enviarse nuevamente. Pregunte si algunos inquilinos (tenants) deben permanecer en el protocolo anterior y si se requiere un despliegue canary y rollback.
Respuesta de 30 segundos
“Devolvería 426 solo cuando el protocolo actual impida que el servidor maneje el recurso, mientras que un protocolo de destino compatible sí podría manejarlo. La respuesta debe incluir un valor Upgrade explícito y una explicación legible para humanos o para máquinas. El cliente debe crear la conexión de destino antes de decidir si reintentar; no puede asumir que la solicitud no se ejecutó. Una versión de HTTP totalmente no compatible es 505, un desajuste de enrutamiento puede ser 421 y los errores sintácticos comunes son 400. El gateway debe rastrear el protocolo, la cadena de proxies, los resultados de la actualización, el comportamiento de la caché y la amplificación de reintentos.”
Respuesta detallada
Paso 1: Confirmar la condición desencadenante
La condición fundamental es “el protocolo actual no es adecuado, pero una actualización podría tener éxito”. El servidor necesita un protocolo de destino conocido y una ruta de actualización real. Clientes desconocidos, campos faltantes y una versión antigua de la aplicación no califican automáticamente.
Paso 2: Hacer que la respuesta sea procesable
Incluya un campo Upgrade que enumere un protocolo que el servidor acepte, como HTTP/3.0, además de un cuerpo breve o un código de error legible por máquina. No devuelva únicamente un mensaje vago de “por favor actualice” ni exponga la topología interna.
HTTP/1.1 426 Upgrade Required
Upgrade: HTTP/3.0
Content-Type: application/problem+json
{"type":"https://example.test/problems/upgrade-required","title":"Upgrade required"}Paso 3: Separar la actualización de la conexión del reintento de la aplicación
El cliente primero establece la conexión con el protocolo de destino y luego decide si reenvía la solicitud original. La actualización de la conexión es una acción de transporte o protocolo, no un cambio en un campo de la aplicación. Para un POST no idempotente, el cliente necesita una clave de idempotencia, una consulta del estado de ejecución y un contrato de reintento específico de la API.
Paso 4: Mantener TLS en la capa correcta
El código 426 no reemplaza un error de certificado o de enlace TLS. La RFC 2817 aborda la actualización de HTTP/1.1 a TLS, pero los despliegues modernos usualmente negocian TLS y las versiones de HTTP mientras establecen la conexión. Si la solicitud nunca alcanza una etapa en la que se pueda generar una respuesta HTTP, registre una falla de enlace en lugar de fabricar un 426.
Paso 5: Trazar los límites de los códigos de estado
400 significa sintaxis o contenido de solicitud inválido; 421 significa que la solicitud llegó a un servidor que no puede producir una respuesta para esa solicitud; 505 significa que el servidor no admite la versión de HTTP utilizada en la solicitud. 426 promete una posible continuación tras la actualización, por lo que no debe ocultar un protocolo de destino no disponible o un recurso inexistente.
Paso 6: Diseñar el comportamiento de proxies, cachés y reintentos
Un proxy puede terminar una conexión y crear otra solicitud, mientras que los clientes pueden reintentar automáticamente. Establezca una política de Cache-Control deliberada para que una caché compartida no conserve un error de migración indefinidamente. Registre el protocolo original, el resultado negociado, la cadena de proxies y el conteo de reintentos. Alinee los presupuestos de reintento con los límites de tasa (rate limits) y los circuit breakers.
Paso 7: Proteger los despliegues canary y el rollback
Implemente en canary para los clientes que puedan usar el protocolo de destino, observe la tasa de éxito, la latencia, el tipo de error y las escrituras duplicadas, y luego expanda. Mantenga el protocolo anterior hasta que se complete la migración y prepare el rollback por cliente, inquilino o región. El conteo de 426 por sí solo no es prueba de éxito porque los intermediarios pueden consumir o reescribir la respuesta.
Paso 8: Verificar la recuperación del cliente
Pruebe GET, PUT idempotente, POST no idempotente, conexiones persistentes, reenvío de proxies, aciertos en caché (cache hits), fallas de TLS, valores de actualización desconocidos y un protocolo de destino no disponible. Verifique la reconexión, las escrituras duplicadas, el contexto de autenticación y la telemetría que separa 426, 421, 505 y fallas de enlace.
Respuesta modelo
Primero verificaría que el protocolo actual realmente bloquee el procesamiento del recurso, mientras que el protocolo de destino esté disponible y cuente con una ruta de actualización definida. Luego devolvería 426 con Upgrade: HTTP/3.0 y un error legible por máquina, sin filtrar detalles internos. El cliente debe establecer HTTP/3 y usar la idempotencia del método, una clave de idempotencia y una consulta de ejecución antes de reintentar; no puede inferir que la escritura original no ocurrió. Las fallas de enlace TLS pertenecen a la capa de conexión, una versión de HTTP completamente no compatible es 505, un desajuste de enrutamiento puede ser 421 y las solicitudes mal formadas son 400. Realizaría un despliegue canary según la capacidad del cliente, monitorearía el protocolo, la cadena de proxies, las escrituras duplicadas y la tasa de éxito, establecería límites de caché y reintentos, y preservaría una ruta de rollback al protocolo anterior. Las pruebas cubrirían métodos, proxies, cachés, conexiones persistentes y un protocolo de destino no disponible.
Errores comunes
Tratar 426 como un error genérico de cliente desactualizado
426 se refiere a una actualización de protocolo que podría permitir servir el mismo recurso. Una versión antigua de la aplicación, un campo faltante o un permiso denegado requieren su propio contrato a nivel de aplicación.
Asumir que el campo Upgrade realiza la actualización
La respuesta le indica al cliente qué hacer a continuación; el cliente aún debe crear una conexión adecuada. Los servidores y proxies deben admitir el protocolo de destino, la autenticación, el enrutamiento, los límites y la telemetría.
Reproducir automáticamente solicitudes no idempotentes
El código 426 puede ocurrir cerca del límite de procesamiento de la solicitud. Sin una clave de idempotencia o una consulta de ejecución, reenviar un POST puede generar efectos secundarios duplicados.
Preguntas de seguimiento y respuestas
¿Cuál es la diferencia fundamental entre 426 y 505?
426 indica que una actualización podría hacer que la solicitud tenga éxito y señala el protocolo de destino. 505 indica que el servidor no admite la versión de HTTP utilizada por la solicitud y normalmente no ofrece una promesa de actualización.
Si un edge proxy termina HTTP/3, ¿puede el origen devolver 426?
El edge debe manejar la negociación y el enrutamiento en su límite y pasar el contexto necesario al origen. Si el origen no puede ver el protocolo real del cliente, no debe inferirlo a partir de los campos de conexión; en su lugar, registre el protocolo del proxy y la semántica de reenvío.
¿Se puede almacenar en caché una respuesta 426?
Solo cuando la clave de caché, la capacidad del cliente y el plan de migración sean explícitos. Por defecto se debe evitar que una caché compartida conserve un error de migración de protocolo durante un período prolongado, utilizando campos de respuesta que expresen cualquier política de corta duración.
¿Cómo puede un POST recuperarse de forma segura de un 426?
Utilice una clave de idempotencia, una consulta del estado de ejecución y un presupuesto de reintentos del cliente. Establezca primero la conexión de destino y luego confirme si la solicitud original se ejecutó. Si no se puede confirmar, reporte un estado pendiente en lugar de reintentar a ciegas.
¿Cuándo se debe rechazar la conexión en lugar de devolver 426?
Si TLS, ALPN o una negociación de protocolo de nivel inferior falla antes de que se pueda producir una respuesta HTTP, cierre la conexión y registre el motivo. 426 requiere una respuesta HTTP que se pueda enviar y una sugerencia de actualización procesable.
¿Cómo se demuestra que la migración no afectó negativamente a los usuarios?
Realice un despliegue canary por capacidad de cliente y compare el éxito posterior al 426, la latencia, las escrituras duplicadas, las fallas de autenticación, la distribución de proxies y el tiempo de rollback. Las métricas deben separar los reintentos de edge, origen y cliente en lugar de solo contar las respuestas 426.