1. Pregunta
Una API de datos B2B presta servicio a miles de equipos de desarrolladores. Tras un lanzamiento, los tickets de soporte indican cada vez más que las solicitudes fallan sin explicar cómo solucionarlas. El equipo de ingeniería desea exponer más logs internos, mientras que el equipo de ventas solicita textos de error personalizados para cada cliente. Como product manager, diseña una experiencia de errores de API accionable sin romper los clientes existentes.
2. Restricciones y aclaraciones
- Separa las fallas de entrada del cliente, autenticación y autorización, límites de tasa (rate-limit), dependencias y servicios internos; no reduzcas cada falla a un único 500.
- Haz que la respuesta sirva para el procesamiento automatizado por máquinas, el diagnóstico de los desarrolladores y la presentación al usuario final sin confundir sus necesidades.
- Los SDK y los formatos de logs existentes no pueden cambiar todos de inmediato, por lo que el plan debe admitir clientes antiguos y una migración gradual.
- Nunca devuelvas trazas de pila (stacks) sensibles, tokens, datos de usuarios o topología interna directamente a los emisores de las llamadas.
3. Marco de diagnóstico del producto
Divide el problema en tres preguntas: qué ocurrió, quién puede solucionarlo y qué debería suceder a continuación. Una respuesta de error necesita un código estable legible por máquinas, un resumen seguro para humanos, detalles estructurados opcionales y un ID de correlación de soporte; la documentación y los SDK mapean el código a una solución. El análisis de producto debe rastrear la tasa de recuperación tras un error, los reintentos repetidos, el tiempo desde la falla hasta el éxito, los tickets de soporte por clase de error y la distribución de versiones, no solo la tasa total de fallas.
4. Solución de referencia
errorResponse:
status: canonicalStatusCode
code: stableProductErrorCode
message: safeHumanSummary
details:
reason: machineActionableReason
fieldViolations: optionalFieldErrors
retryAfter: optionalDelay
requestId: supportCorrelationId
docsUrl: versionedFixGuide
clientFlow(error):
classify(error.status, error.code)
if retryable: backoffAndRetry(error.details.retryAfter)
else if fieldError: highlightFields(error.details.fieldViolations)
else: showDocsAndRequestId(error.docsUrl, error.requestId)Define un conjunto reducido de códigos de estado canónicos estables y luego utiliza códigos de error de producto para causas accionables. Coloca las infracciones de campos, los tiempos de reintento y los enlaces a la documentación en detalles estructurados. La consola muestra los pasos de reparación según el código, mientras que los SDK mapean los errores a tipos capturables y preservan el código original. El servicio registra diagnósticos completos de forma interna, pero devuelve únicamente un resumen seguro y el ID de correlación.
5. Compensaciones y estrategia de despliegue
Los códigos de error más específicos hacen que la orientación sea más precisa, pero aumentan los costos de compatibilidad y documentación. Comienza con los errores de alto volumen que los desarrolladores pueden solucionar y luego añade detalles para clases más pequeñas; no crees un protocolo personalizado por cliente (tenant). Los nuevos campos deben mantener la compatibilidad hacia atrás. Una vez que el significado de un código sea público, mantenlo estable: los clientes antiguos continúan recibiendo el formato anterior mientras que los SDK más recientes optan por los detalles estructurados. Las respuestas de falla parcial merecen precaución porque agregan ramificaciones en los clientes; introdúcelas únicamente cuando una API por lotes tenga una necesidad clara.
6. Verificación y observabilidad
- Muestrea tickets de soporte y logs de llamadas, etiquetando cada falla como diagnosticable, solucionable y si se reintentó innecesariamente o no.
- Escribe pruebas de contrato para autenticación, validación de campos, límites de tasa, tiempos de espera de dependencias y fallas desconocidas, verificando el estado, el código y la URL de documentación.
- Despliega gradualmente el nuevo formato y compara la tasa de recuperación, los reintentos repetidos, el volumen de tickets y la tasa de captura de excepciones en los SDK.
- Monitorea códigos desconocidos, la proporción de clientes antiguos, la conversión de clics en la documentación a llamadas exitosas y la fuga de campos sensibles en las respuestas de error.
7. Errores comunes
- Exponer más logs o trazas de pila sin proporcionar a los emisores de llamadas un código estable y una acción de reparación.
- Codificar todo el significado de negocio en el estado HTTP, obligando a los clientes a analizar cadenas de texto.
- Incluir excepciones internas, tokens o parámetros de solicitud completos en un mensaje supuestamente amigable.
- Renombrar o eliminar códigos en un lanzamiento y romper los SDK antiguos durante la actualización.
8. Puntos de evaluación de la entrevista
Clasifica los errores según la responsabilidad de reparación
El candidato debe separar las fallas de entrada, permisos, límites de tasa, dependencias e internas, e indicar la acción del emisor y la responsabilidad del servicio para cada una.
Diseña un modelo de errores estable y seguro
La respuesta debe incluir códigos legibles por máquinas, resúmenes seguros, detalles estructurados, IDs de correlación y documentación versionada sin exponer aspectos internos.
Conecta la experiencia con las métricas del producto
El candidato debe utilizar la tasa de recuperación, los reintentos repetidos, el tiempo de resolución, los tickets y la distribución de versiones en lugar de limitarse a la tasa de fallas.
Planifica una migración compatible
El candidato debe explicar la compatibilidad con formatos antiguos, la adopción gradual en los SDK, los criterios de despliegue y reversión (rollback), y cuándo evitar introducir un protocolo complejo de falla parcial.