Saltar al contenido principal

Solución de problemas técnicos

Introducción​

Incluso las API bien documentadas y robustas pueden plantear desafíos inesperados durante la integración. Desde problemas de autenticación hasta la gestión de límites de velocidad y el análisis de respuestas complejas, estos obstáculos comunes pueden ralentizar el desarrollo y complicar los despliegues en producción. Los siguientes consejos de solución de problemas tienen como objetivo ayudarte a identificar patrones comunes de errores, comprender sus causas raíz y aplicar soluciones prácticas, permitiéndote construir aplicaciones confiables sobre la API.

Problemas más comunes con las API REST​

Esta sección describe los problemas comunes que puedes encontrar al usar la API y proporciona orientación sobre cómo resolverlos. Si continúas experimentando problemas después de intentar estas soluciones, considera contactar a nuestro equipo de soporte.

Errores de autenticación​

Síntomas:

  • Recibir una respuesta HTTP 401 (No autorizado) o 403 (Prohibido).
  • Respuestas que indican "Token inválido" o "Token expirado".

Causas posibles:

  • Falta o formato incorrecto del encabezado de Autorización.
  • Token de acceso expirado o inválido.
  • Credenciales incorrectas o nombres de campos incorrectos en los datos del formulario al llamar al endpoint /login.

Soluciones:

  • Asegúrate de haber incluido el Bearer access_token en el encabezado de Autorización para los endpoints protegidos.
  • Los JSON Web Tokens (JWTs) generados por la API tienen una vida útil limitada. Si el token ha expirado, solicita un nuevo token a través de /login utilizando credenciales válidas.
  • Verifica que tu username y password sean correctos y no hayan sido cambiados o revocados.

Solicitudes con payloads inválidos o mal formados​

Síntomas:

  • Recibir un error HTTP 400 (Solicitud incorrecta).
  • Mensajes de error relacionados con JSON mal formado o campos obligatorios faltantes.

Causas posibles:

  • El payload JSON no está correctamente formateado (por ejemplo, faltan llaves o comas).
  • Parámetros obligatorios no incluidos.
  • Tipo de contenido no JSON en los encabezados de la solicitud.

Soluciones:

  • Usa un validador de JSON antes de realizar la solicitud para verificar la sintaxis del JSON.
  • Consulta la documentación del endpoint para asegurarte de que todos los campos obligatorios (por ejemplo, media, bodySite) estén presentes.
  • Incluye Content-Type: application/json en el encabezado de la solicitud para los servicios clínicos.

Problemas de carga y calidad de imágenes​

Síntomas:

  • Recibir respuestas HTTP 400 o 422 (Entidad no procesable) que indican datos o formato de imagen inválidos.
  • Resultados inconsistentes o inesperados de /diagnosis-support o /severity-assessment.

Causas posibles:

  • Formatos de imagen no compatibles (solo se admiten imágenes codificadas en Base64).
  • El archivo de imagen está dañado o incompleto.
  • Mala calidad de imagen que resulta en baja confianza de los modelos de visión por computadora clínica.
  • Imágenes no dermatológicas enviadas a servicios que esperan contenido dermatológico.

Soluciones:

  • Confirma que la imagen esté codificada en Base64 y utilice un formato de archivo compatible, como JPEG o PNG.
  • Verifica que el archivo de imagen no esté dañado y que los datos de la imagen estén correctamente codificados.
  • Usa imágenes de mayor resolución sin desenfoque, con buena iluminación y enfoque.
  • Asegúrate de que la imagen sea de naturaleza dermatológica. Las imágenes no dermatológicas pueden hacer que el modelo de dominio del dispositivo devuelva resultados altamente inciertos.

Resultados poco claros o inesperados​

Síntomas:

  • Distribución inesperada de posibles categorías ICD-11, signos visuales predichos o máscaras, o puntajes de sistemas de puntuación automática.
  • Resultados que difieren significativamente de las expectativas clínicas.

Causas posibles:

  • La imagen de entrada puede no mostrar claramente la condición de la piel relevante.
  • La confianza del modelo para identificar ciertas condiciones puede ser baja debido a imágenes ambiguas (por ejemplo, imágenes que muestran más de un trastorno cutáneo).
  • La generación de resultados clínicos depende de múltiples modelos; si los modelos previos (por ejemplo, dominio o calidad) producen salidas inciertas, las interpretaciones clínicas posteriores pueden verse afectadas.

Soluciones:

  • Proporciona imágenes que muestren claramente el área de piel afectada, preferiblemente con iluminación y enfoque adecuados.
  • Revisa la documentación para confirmar que la condición enviada está dentro del conjunto de condiciones admitidas para los endpoints /diagnosis-support o /severity-assessment.
  • Si es posible, proporciona ángulos adicionales de la imagen o mejora las condiciones de captura para ayudar al modelo a desempeñarse con mayor precisión.

Problemas de red y rendimiento​

Síntomas:

  • La API no es accesible.
  • Tiempos de respuesta lentos o solicitudes que exceden el tiempo de espera.
  • Errores de conectividad intermitente o de indisponibilidad del servidor (por ejemplo, HTTP 502 o 503).

Causas posibles:

  • Bloqueos de DNS o firewall.
  • Errores inesperados en la lógica del servidor.
  • Tiempo de inactividad temporal del servidor o mantenimiento.
  • Alta carga del servidor.
  • Mala conexión de red en el lado del cliente.
  • Tamaños grandes de imágenes que causan tiempos de procesamiento prolongados.

Soluciones:

  • Verifica la página de estado de la API (si está disponible) o contacta al soporte para ver si hay mantenimiento en curso o una interrupción del servicio conocida.
  • Comprueba si la configuración de tu red o firewall permite solicitudes salientes al dominio web de la API.
  • Si encuentras problemas temporales del servidor, espera unos minutos antes de volver a intentarlo.
  • Reduce el tamaño del archivo de imagen (sin comprometer la claridad) para mejorar los tiempos de procesamiento. El rendimiento no se verá afectado, ya que nuestros modelos de visión por computadora están diseñados para trabajar con imágenes de calidad media.
  • Asegúrate de que tu cliente tenga una conexión a internet estable y considera ajustar los tiempos de espera de las solicitudes.

Limitación de velocidad​

Síntomas:

  • Recibir respuestas HTTP 429 (Demasiadas solicitudes).
  • Incapacidad temporal repentina para acceder a endpoints protegidos incluso con autenticación válida.

Causas posibles:

  • Superar el límite de solicitudes permitido dentro de una ventana de tiempo determinada.
  • Enviar múltiples solicitudes rápidamente o realizar operaciones masivas sin el ritmo adecuado.

Soluciones:

  • Al recibir un error 429, espera la duración especificada en el encabezado Retry-After antes de enviar otra solicitud. Si este encabezado no está presente, espera unos segundos y vuelve a intentarlo.
  • Siempre que sea posible, programa o agrupa las solicitudes para evitar enviar muchas en un corto intervalo.
  • Consulta los límites de velocidad establecidos por la API y ajusta tu uso para permanecer dentro de las cuotas permitidas.
  • Almacena en caché información estática o que cambia raramente para minimizar las llamadas repetidas a la API.

URLs incorrectas, obsolescencia de endpoints o incompatibilidades de versión​

Síntomas:

  • Recibir un error HTTP 404 (No encontrado).
  • Errores inesperados después de una actualización reciente de la API o lanzamiento de una nueva versión.
  • Errores que indican que ciertos parámetros o endpoints no son reconocidos.

Causas posibles:

  • Errores tipográficos en la URL.
  • Uso de endpoints o parámetros obsoletos.
  • No seguir la documentación más reciente de la API o las pautas de versión.

Soluciones:

  • Confirma que la URL base y/o los segmentos de ruta coincidan exactamente con la documentación. Además, verifica que estás utilizando el verbo HTTP correcto (GET o POST).
  • Verifica que estás utilizando las URLs de endpoint más recientes y los esquemas de datos para el cuerpo de la solicitud.
  • Si los endpoints han quedado obsoletos, actualiza tu aplicación cliente para usar las alternativas recomendadas.
  • Consulta los registros de cambios o notas de la versión para obtener detalles sobre comportamientos o campos de datos actualizados.

¿Necesitas más ayuda?​

Si las soluciones anteriores no resuelven tu problema, por favor contacta a nuestro equipo de soporte técnico en support@legit.health. Incluye los siguientes detalles en tu solicitud:

  • El endpoint que estabas utilizando.
  • Detalles de la solicitud y respuesta (por ejemplo, marcas de tiempo, encabezados, payloads y mensajes de error).
  • Pasos para reproducir el problema.

Esta información nos ayuda a diagnosticar y resolver tu problema de manera más eficiente.