Lo que evalúa el entrevistador
Una API multi-tenant emite errores desde el gateway, la aplicación y los trabajos asíncronos, por lo que los clientes no pueden analizar las fallas de manera confiable. Usando RFC 9457, diseña un contrato de error compartido y explica códigos de estado, tipo de medio, URIs de tipo, validación por lotes, reintentos, redacción de datos sensibles y compatibilidad de versiones.
Contexto y restricciones
- Una solicitud puede atravesar una CDN, un API gateway, un servicio de negocio y una cola.
- Los clientes deben distinguir errores de entrada corregibles, fallas de autorización, limitación de tasa (throttling) y fallas transitorias.
- Los detalles no deben exponer trazas de pila (stacks), claves, datos de aislamiento de inquilinos (tenants) ni nombres de host internos.
- Los clientes existentes analizan campos heredados (legacy), por lo que la migración debe mantener la compatibilidad hacia atrás.
Separar la semántica HTTP del detalle de negocio
El estado HTTP expresa el resultado a nivel de protocolo; el cuerpo de Problem Details explica la causa. Elige 400, 401, 403, 404, 409, 429 y 5xx según su semántica en lugar de devolver 200 para cada falla. Usa una URI estable en type para la clasificación por máquinas, un title para presentación y un detail específico de la solicitud.
Definir un contrato extensible mínimo
Los miembros principales son type, title, status, detail y instance. Nombra las extensiones explícitamente, como errors para problemas de campos y retryAfter para una sugerencia de espera del cliente. La documentación de cada tipo debe indicar su significado, los códigos de estado permitidos y la acción del cliente; los clientes no deben ramificar su lógica basándose en títulos en lenguaje natural.
Compartir un límite de error entre capas
Los errores de tiempo de espera, autenticación y throttling generados por el gateway usan el mismo tipo de medio, pero no deben hacerse pasar por un tipo de negocio de la aplicación. Los servicios mantienen códigos de error internos para telemetría mientras exponen únicamente tipos aprobados. Propaga un ID de correlación entre servicios sin copiar texto con detalles sensibles.
Preguntas aclaratorias antes de responder
- ¿Los clientes ramifican su lógica según el estado,
typeo uncodeheredado? Esto determina el adaptador de migración. - ¿Puede una sola respuesta contener múltiples fallas de validación de campos? Esto determina la estructura y la garantía de orden de
errors. - ¿El gateway puede comprender errores de negocio, o solo crea y transporta errores de infraestructura? Esto determina la propiedad de los tipos.
Estructura de respuesta en 30 segundos
“Preservaría el estado HTTP correcto y devolvería application/problem+json con type, title, status, detail estables y un instance opcional. Los clientes ramifican según el estado y type, nunca según texto en prosa; el gateway es propietario únicamente de sus tipos de error. La validación, las sugerencias de reintento, los IDs de correlación y las reglas de redacción se convierten en un contrato versionado verificado mediante matrices de compatibilidad y la ruta de solicitud real.”
Análisis detallado paso a paso
Comienza con un registro de tipos de error. Cada tipo tiene una URI, miembros públicos, estados permitidos, acción del cliente y nivel de seguridad. Las fallas de validación usan 400 con problemas de campos bajo errors; la identidad ausente y los permisos insuficientes permanecen como 401 y 403; los conflictos de concurrencia optimista usan 409; el throttling usa 429 con una sugerencia de espera accionable; las fallas desconocidas usan 500 o 503 y un tipo público genérico.
Mantén Content-Type consistente con la representación. Un valor de instance puede identificar una solicitud para soporte, pero detail no debe contener URLs completas, SQL, trazas de pila ni identificadores de inquilinos. Los registros (logs) conservan la causa interna, el ID de correlación y los campos de auditoría de seguridad; el cliente recibe únicamente contenido filtrado por políticas.
Para la validación por lotes, define si se permiten múltiples problemas, cómo se escriben las rutas de los campos y el número máximo de entradas. Los clientes ignoran los miembros de extensión desconocidos. Los nuevos miembros son aditivos; cambiar el significado de un type existente requiere una nueva URI. Un trabajo asíncrono expone su falla a través del recurso del trabajo en lugar de filtrar sincrónicamente detalles internos de la cola.
Respuesta modelo de alta calidad
“Mantendría un registro de tipos y haría que el gateway, los servicios sincrónicos y los trabajos asíncronos emitan application/problem+json compatible con RFC 9457. El estado transmite la semántica del protocolo, type transmite una categoría estable y detail describe únicamente esta solicitud. La validación de campos utiliza una extensión errors acotada; 429 incluye una sugerencia de espera procesable; 500 y 503 usan tipos públicos genéricos mientras las trazas de pila permanecen en los logs. Durante la migración mantengo el code heredado, y luego migro a los clientes mediante pruebas de contrato, matrices de compatibilidad y auditorías de redacción de datos sensibles.”
Errores comunes
- Devolver 200 con un campo de falla de negocio, provocando que cachés, monitores y sistemas de reintento infieran éxito.
- Ramificar lógica basándose en
titleodetail, haciendo que las traducciones o cambios de redacción rompan los clientes. - Permitir que cada servicio invente URIs de
type, impidiendo una agregación consistente. - Devolver trazas de pila, SQL, dominios internos o identificadores completos de inquilinos en
detail. - Convertir un tiempo de espera agotado del gateway en un error de negocio, provocando reintentos incorrectos u orientación errónea al usuario.
Síntomas de falla y soluciones
Cuando un cliente no puede decidir si reintentar, generalmente el estado, el tipo y la guía de reintento no coinciden. Construye primero el registro, mapea cada capa a un conjunto público reducido, define un valor predeterminado seguro para tipos desconocidos y rastrea la causa interna con un ID de correlación.
Implementación en producción
Centraliza la serialización en una biblioteca compartida o en un adaptador perimetral (edge) mientras preservas la selección del estado en el límite del servicio. La validación de esquemas limita la longitud de extensiones, el conteo de arrays y los formatos de URI; redacta datos sensibles antes de la serialización en lugar de confiar únicamente en el gateway. Define backoff exponencial, jitter y condiciones de idempotencia por separado para 429, 503 y tiempos de espera de red para evitar tormentas de reintentos.
Lista de verificación para verificación
Las pruebas de contrato cubren el estado, el tipo de medio, los miembros requeridos y las extensiones de cada tipo público. Las pruebas de integración cruzan el gateway, el servicio y la cola, y validan los IDs de correlación y la redacción de datos. Las pruebas de compatibilidad usan un cliente heredado para verificar la tolerancia a miembros desconocidos y la preservación de code. Las pruebas de carga miden la latencia de serialización, el muestreo de logs y la amplificación de reintentos bajo throttling.
Preguntas de seguimiento y respuestas
¿Por qué no definir un único código de error de negocio?
Un solo código no puede expresar la semántica de almacenamiento en caché HTTP, autenticación, throttling y reintentos. El estado permite que la infraestructura genérica se comporte correctamente; type transporta la categoría de negocio estable. Tienen responsabilidades diferentes.
¿Debe ser accesible una URI de type?
La especificación permite URIs relativas o absolutas. Elige una forma estable y documentable, pero no hagas que la disponibilidad de una página de documentación sea un requisito previo para el manejo por parte del cliente.
¿Cómo evitas que el cuerpo del error filtre datos?
Usa una lista de permisos de miembros públicos, límites de longitud y escaneo de patrones sensibles. Mapea las excepciones internas a tipos genéricos y conserva únicamente un ID de correlación para soporte. Las pruebas de seguridad cubren consultas entre inquilinos, fallas de autorización y rutas de excepción.
Rúbrica de evaluación
- Precisión semántica: distingue el significado del estado HTTP de los miembros de Problem Details.
- Diseño del contrato: propone tipos estables, extensiones y versionado.
- Conciencia de límites: cubre gateways, trabajos, redacción de datos y tormentas de reintentos.
- Viabilidad de implementación: incluye un registro, límite de serialización, matriz de compatibilidad y pruebas.
- Control de riesgos: evita fugas de información y no trata tipos desconocidos como reintentables por defecto.
Verificación de cumplimiento
Confirma que los códigos de estado, campos de tipo, redacción de datos y límites de reintento permanezcan consistentes.
Lista de verificación para la respuesta en la entrevista
Comienza con la semántica de estado, luego explica que type es el identificador estable para máquinas y que detail no es una clave de contrato. Agrega evidencia de propiedad del gateway, validación, reintento, redacción y compatibilidad.
Conclusión en una sola frase
Estandariza los errores haciendo que el estado exprese la semántica del protocolo, type exprese una clasificación estable y las extensiones expresen detalles procesables, con pruebas de seguridad y compatibilidad protegiendo el límite.