¿Cómo diseñar mensajes de error de API?

¡Hola! Como proveedor de API, he estado en las trincheras del diseño de mensajes de error de API desde hace bastante tiempo. Puede parecer una pequeña parte de todo el asunto de la API, pero créanme, puede mejorar o deshacer la experiencia del usuario. En este blog, compartiré algunos consejos sobre cómo diseñar mensajes de error de API que sean realmente útiles.

En primer lugar, hablemos de por qué son importantes los buenos mensajes de error. Cuando un usuario sufre un error al utilizar su API, puede resultar realmente frustrante. Probablemente estén en medio de algo importante y, de repente, se queden estancados. Un mensaje de error bien diseñado puede convertir ese momento frustrante en una oportunidad de aprendizaje. Puede ayudar al usuario a comprender qué salió mal y cómo solucionarlo, ahorrándole tiempo y dolores de cabeza.

Sea claro y conciso

Lo más importante acerca de un mensaje de error es que debe ser claro. No desea utilizar jerga o lenguaje demasiado técnico que el usuario no entienda. Por ejemplo, en lugar de decir "Hubo un problema con el código de estado de entidad no procesable HTTP 422 debido a una violación de las restricciones de integridad de datos especificadas en el esquema", podría decir "Los datos que envió no coinciden con el formato requerido. Verifique su entrada y vuelva a intentarlo".

También es fundamental ser conciso. Los usuarios no quieren leer un párrafo largo y sinuoso para descubrir qué está mal. Mantenga sus mensajes breves y directos. Una buena regla general es no escribir más de dos o tres frases.

Proporcionar información procesable

Un mensaje de error no sólo debe indicarle al usuario qué salió mal, sino también darle una idea de cómo solucionarlo. Por ejemplo, si el usuario intenta acceder a un punto final que requiere autenticación y no ha proporcionado credenciales válidas, el mensaje de error podría decir "Debe proporcionar credenciales de autenticación válidas para acceder a este punto final. Incluya su clave API en el encabezado de la solicitud".

Supongamos que es un proveedor de API para un distribuidor farmacéutico y tiene puntos finales para medicamentos comocrizotinib,brigatinib, yHidrato de clorhidrato de capmatinib. Si un usuario intenta obtener información sobre un medicamento pero utiliza una identificación de medicamento incorrecta, su mensaje de error podría decir "La identificación de medicamento que proporcionó es incorrecta. Verifique la identificación e inténtelo nuevamente. Puede encontrar las identificaciones correctas en nuestra página de documentación".

Utilice un formato coherente

La coherencia es clave cuando se trata de mensajes de error. Utilice el mismo formato para todos sus mensajes de error en su API. Esto facilita que los usuarios comprendan y procesen rápidamente la información. Por ejemplo, puede comenzar todos sus mensajes de error con un título breve y descriptivo en negrita, seguido de una explicación más detallada.

**Error: entrada no válida** La entrada que proporcionó para el campo de nombre del medicamento no es válida. Debe ser una cadena sin caracteres especiales. Corrija la entrada e inténtelo de nuevo.

Incluir códigos de error

Los códigos de error son una excelente manera de proporcionar información más detallada a los desarrolladores. Pueden utilizar estos códigos para identificar y solucionar problemas rápidamente en sus aplicaciones. Asegúrese de que sus códigos de error sean únicos y fáciles de entender. Puede tener una sección separada en la documentación de su API que explique qué significa cada código de error.

Por ejemplo, podría tener un código de error "ERR - 001" para "Clave API no válida" y un código de error "ERR - 002" para "Falta un parámetro requerido". Su mensaje de error podría decir algo como "Código de error: ERR - 001. La clave API que proporcionó no es válida. Verifique su clave e inténtelo nuevamente".

Ofrecer información de soporte

A veces, los usuarios pueden necesitar más ayuda de la que puede proporcionar el mensaje de error. En estos casos, es una buena idea incluir información de soporte en sus mensajes de error. Podría ser un enlace a su página de soporte, una dirección de correo electrónico o un foro donde los usuarios pueden hacer preguntas.

Por ejemplo, "Si aún tiene problemas después de seguir los pasos anteriores, visite nuestra página de soporte para obtener más ayuda".

Pruebe sus mensajes de error

Antes de lanzar su API al público, asegúrese de probar minuciosamente sus mensajes de error. Pruebe diferentes escenarios que podrían provocar errores y vea cómo se ven y se sienten los mensajes. También puede recibir comentarios de otros desarrolladores o usuarios para ver si los mensajes son claros y útiles.

Considere la localización

Si su API es utilizada por una audiencia global, es posible que desee considerar localizar sus mensajes de error. Esto significa proporcionar los mensajes en diferentes idiomas. Puede marcar una gran diferencia en la experiencia del usuario para personas que no hablan inglés.

Conclusión

Diseñar buenos mensajes de error de API es una parte importante de ser un proveedor de API. Al ser claro, conciso y proporcionar información procesable, puede ayudar a sus usuarios a tener una mejor experiencia al usar su API. Recuerde utilizar un formato coherente, incluir códigos de error, ofrecer información de soporte, probar sus mensajes y considerar la localización si es necesario.

Si está interesado en utilizar nuestra API para sus necesidades de distribución farmacéutica, ya sea paracrizotinib,brigatinib, oHidrato de clorhidrato de capmatinib, nos encantaría charlar contigo. Comuníquese con nosotros para iniciar el proceso de adquisición y negociación.

Referencias

• Mejores prácticas de diseño de API RESTful, O'Reilly Media
• Diseño de API para desarrolladores, Google Developers